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The cost of software is fast bacomitg a major slice of DDD's 
automated data processing budget. Most of this oost is 
directly related to the mainteaance of existing software. A 
primary cause is poor or non-existant documentation which 
leads to high costs when it cones time to change the sofo- 
wace to correct errors, add enhancements, or to comply with 
changes in Federal re gulation s/DOD policies. 

This thesis looks at the various software engineering 
techniques available to programmers and managers for the 
development of software documentation. A set of guidelines 
for an "ideal” program maintenance manual is proposed. These 
guidelines are based on current DoD standards, examples of 
software maintenance manuals from industry, and applications 
of current software engineering practices. 
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I. INTRODtJCTIDN 



A. THE NEED FOR DOCD HERT ATION 

( 

A rscent Govenmsnt Accouatiag Dffirs report, reviewing 
computer software maintenance in FeieraL ADP agencies, 
produce! some interesting observations *Ref. 1 ]. 

1. Two thirds of the programmers at 13 Federal ADP agen- 
cies spent their time on software b aintenance. 

2. The Department of Defense will spend approximately $3 
billion in 1981 on software. 

3. Agencies have made little effort to effectively 
manage and minimize the resources reauired to main- 
tain computer software. 

4. Software is often maintained by oeople who did not 
develop it. 

5. Poor document ation often results in rebuilding an 
entire system of programs because understanding and 
modifying an existing program may be more trouble and 
expense xhen building a new one. 

The Federal Government is not alone in its software mainte- 
nance 'crises’. All ADP users, including private industry, 
are being swallowed up by the ’’tar-pits of software manage- 
ment” as Fred Brooks has so vividly described [Ref. 2]. The 
costs to the government and private industry, in terms of 
dollars and manpower, is increasing at an alarming rate. 
Costs for software (procurement and maintenance) are 
expected to reach J200 billion by 1985. DOD estimates it 
will spend 350 billion by 1990 for embedded software alone 
[ Ref. 3, 4 ]. 

A large share of these costs are for software mainte- 
nance (see Figure 1. 1). Various studies have shown chat 
from forty to ninety-five percent of manpower effort in most 
ADP organizations is spent on software maintenance 
[Ref. 5-14]. 
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Figure 1.1 Hanpower Loadiag acd Maiatenance costs. 
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There are many reasons for the wife /ariation ia effort 
being devoted to software maint e nanoe, horfever, a definition 
of maintenance should be presented first. Software mainte- 
nance is best defined as; 

That activity which is concerned with making changes to 
software for the purpose of improving or correcting the 
software without introducing new errors [ Bef. 15]. 



Despite the fact that large amounts of manpower and other 
resources are spent on software maintenance, few managers 
comprehend the underlying reasons. There are four basic 
issues behind the problems of software maintenance: 

• Maintenance is considered less glamorous, interesting 
and challenging as comoared to system design ana 
programming; hence, there is little incentive for 
computer personnel to become involved in maintenance 
activities (or document their time and effort spent on 
maintenance) . 

• During development it is often too early in the project 
to forsee problems which may occur during maintenance; 
as a consequence maintainability (the prcoerty of soft- 
war e which makes maintenance activities easy to 
perform) is not provided for in the system design. 

• Project management does not always recognize that main- 
tainability considerations should be an integral part 
of the design process. 

• It is very difficult to modify or simplify the struc- 
ture of a program after the program has been written. 
[Ref. 15] 

Weapon system software and real-time system software 
used extensively by the Department of Defense (DOD) suffers 
from similar problems [Hef. 16]. De Roze ‘Ref. 17] reports 
that hir Force avionics software costs about $75 per 
instruction to develop, but maintenance costs are around 
$4,000 per instruction. SAGS, a military defense system, had 
an average annual cost of 29 million dollars after ter. years 
of operation compared to an original development cost of 250 
million dollars [Ref. 18]. 
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The need for efficient, cost effecti/a software Mainte- 
nance is important because "....of the need to keep DOD 
iT 2 el~tiae weapon system software operatiaj as error free as 
possible and the need to oheck the escalating cost 
associated with modifying this software" [Ref. 16]. 

Good documentation is seen as one of the best tools for 
improving software maintenance [ Hef. 19], In general, docu- 
mentation serves as a means of communication within an 
organization, especially over time. Documentation facili- 
tates the training of new personnel and aids in modification 
of a software system by people other than the original 
development programmers. Silbsy [Ref. 23] sees documenta- 
tion as addressing three primary groups of people; managers, 
programmers/system analysts, and users. de also argues that 
the software documentation must be clear, comprehensive, 
detailed and well structured in order to be used effec- 
tively. Good documentation can and must provide a great deal 
of useful information. Specifically, this information has to 
communicate to the maintenance personnel enough detail so 
that enhancements and changes to che software can be easily 
made and do not produce unwanted effects in other parrs of 
the system [Ref. 21], Table I lists examples of the types 
of information needed in documentation. 

Documentation has several important uses beyond a 
general description of code. During the software deveiopmenr 
phase it is used for communication berween members of the 
design team, for training new personnel assigned to the 
project and as a basis for design reviews. During tae sofr- 
ware maintenance period the documentation serves again as a 
training base, a guide for modification and error checking, 
as an organized collection of design information, and as a 
historical rrace of the software’s production and operation, 

■fJe wish to emohasize the necessity of considering 
rhe generation of timely do c umenrarr on as an incearaj. 
portion of rhe software deveiopmenr orocess [ Hef . 22]. 
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TABLE I 



Information Doca mentation Provides 



-A historical record of soft<»are systen development. 



-A detailed analysis of software systen design. 



-A well structured source code listing with comments 
on logic and processing flows. 



-Identification, logical, and physical characteristics 
of the Data Base. 



- Requirements, operating environment, and design 
characteristics of the systen. 



-Written instructions for non-AD? personnel that 
explains what the system (software and hardware) 
does and how to use it. 



-Format of input data and output reports. 



-Technical information about data collection 
r equi rements. 



-Detailed specifications, descriptions, and procedures 
for all tests and test data. 






Dccj mentation is an important product of sound software 
engineering design rather rhan a simple by-producn of 
design. Documental. ion has to be clear and concise. The docu- 
menrarion format has to be convenient and simple to use. The 
documentation has to be organized in a hierchical fashion in 
the same manner that the code is structured. All design 
decisions and their impact has to be e<piained, and the 
methodology for modifications decided in advance. Version 
control, and the accounting methods for n odi ficatioa to toe 
software, has to be thorough [Ref. 23]. 
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How much and what types of iocumentation must be decidad 
during the the design phase of system da/alopment. )luch zoo 
often these decisions have besi put off until late in the 
system development cycle which results in poor or 
non-existant documentation [Bef. 1]. 

If we are to improve the maintainability of large soft- 
ware systems we must also '•design for ohange'* as Parnas 
suggests [Ref. 24], This inoludes designing good dooumsnta- 
tion to tell us what a software system does and how it does 
it. 

B. PURPOSE AND ORGANIZATION OF THESIS 

The purpose of this thesis is two-fold. First it will 
examine and review Federal and Department of Defense direc- 
tives on standards for documentation. Included will be a 
summary of the various techniques of documentation from the 
technical literature. Second, a design for a Programmer's 
Maintenance Manual will be presented which incorporates the 
latest concepts in software engineering. The reasons behind 
a particular design and the benefits to be gained will be 
di scussed. 

Chapter II of the thesis will review the concept of the 
software life cycle and how software maintenance activi-ies 
relate to different life cycle piases. A discussion of 
current DOD directives in software management that govern 
weapon system software will be given here. Techniques 
currently available for programmers and software contractors 
for documentation will be described in Chapter III. These 
techniques include methods for representing program logic 
such as structured programming, data structures and 
commented program listings. 
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Chapter IV contains a isscription of a Programmer's 
Maintenance Manual based on DDD r= quire n ents for aoftwara 
documentation and recommendations for ohanges to such a 
manual. The manual is designs! from the point of view that 
the program listing now provides a great deal of "self- 
documentation" resulting froa advances in structured 
programming techniques. In addition the purposes and goals 
of a manual in general are presented with a view that any 
manual should be designed for its intended user. 

Finally, Chapter 7 will provide conclasions and recom- 
mendations. An appendix contains a copy of nhe current DoD 
standard for a program maintenance manual. 
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II. 34CKGPQDND OF SOFFWARB DOCOS ENT ATION 



A. THE SOFTWARE LIFE-CICLE 



All software, tactical weapon syscea and genaral data 
processing, must go through se/aral phases or steps from the 
time a need for a software system is conceived to the point 
where the system is operational. This series of steps is 
generally referred to as the software life cycle. The 
different phases of the life cycle have various names when 
discussed in the literature. Many representations of the 
life cycle are described. Figire 2. 1 depicts one such model 
based on the well understood DOD system life cycle as 
presented in DOD Instruction 5030.1. Figare 2.2 represents a 
more general approach to the life cycle phases. 

Softwa re Development 



In order to understand better what must be done to 
create a software system, an Informal description of each 
phase is provided [Ref. 25]. 

a. System Feasibility and Analysis Phase 



The eventual user of a system discovers a need 
for which a computer based information system or weapon 
system seems to be the answer. The nature of the need is 
analyzed; the outlines of tne type of system that would 
satisfy these needs are established. The most feasible and 
superior concept is defined. 
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DEFENSE SYSTEM 
LIFE CYCLE 
MAJOR PHASE 


SOFTWARE 
LIFE CYCLE 
SUBPHASE 


Conceptua 1 


Re quiram en ts 
Definition 


Requirements 
V alidation 


Validatio n 


V alidation 


Full-Scale 

Development 


Full-Scale 

Development 


Production 


Production 


Deployment 


Debugging 


Fine Tuning 


Support 


Maintenance 


Mo dif ication 



Figure 2.1 DOD Software Life CIrle Model. 

b. Requirements Specif ication Phase 

Functional descriptions of the system are devel- 
oped using a particular formal methodology. Constraints on 
the system's structure and resource usage are identified. 
Economic constraints on the development process itself are 
stated. This phase may be an iterative process that oscil- 
lates between the statement of specifications and refinement 
cf the design. Documentation standards and management objec- 
tives should be defined and listed. This phase is to clearly 
and concisely state what the system is to do - not how to do 
it. 

c. Product Design Phase 

Wcr-ting from the specif ications the overall 
ha rdware /sof tware architecture is conceived. The underlying 
structure of the problem to which this system will be a 
solution is sought out. When this structure becomes clear, a 
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Figure 2.2 Software Life Cycle — General Schematic. 



design of the system is devised. The design is necessarily 
at a gross abstract level of decail. The parts of the system 
and their relationships, the basic aigorirhms that the 
system will use, and the majcr data representations that 
will be needed are created. During this phase the basic 
test plan is developed, preferrably by an independent design 

V. 3 3. IQ • 



d. Detailed Design Phase 

The major parts of the design are now refined in 
detail. Precise algorithms and data strictures are defined 
and spelled out. If not already dons in the Product Design 
Phase, decisions as to which parts of the sysrem will be in 
software and which in hardware are made. Both detail design 
and product design may reguire several levels of refinement 
and reiteration. 

e. Validation Phase 

At this point in the development a check must be 
made to ensure the design, ii all details, fulfills the 
specific at ions. 

f. Programming, Code and Debug Phase 

Encoding of algorithms and data representations 
is accomplished in this phase. Individual modules are 
prepared and tested individually. All basic debugging is 
completed where possible. Some bugs may net appear until all 
che system parts are executed together. 

g. Integrat ion/System Testing Phase 

All coded modules are placed toge-her along wirh 
a sample data base. This produces a physical realization of 
the design. Integration of ail the parts, system testing 
according to the system test plan, and performance evalua- 
tion is accomplished. In many cases a good deal of redesign 
and reimpiementa tion may take place at this time to force 
the actual system to conform to the specifications and 
initial requirements. 
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Software Qper ation 

Everything that happens after rhe software system is 
finished, delivered and finally accepted by the user falls 
into the operational half of the life cycle. 

a. Maintenance Phase 

Tauseworthe offers a definition of maintenance 
as "alterations to the software during the post delivery 
period that do not require a ceinitiatian of the software 
development cycle" [Bef. 26], Me also views the maintenance 
phase as any software related activity, principally suppor- 
tive in form, which keeps the software system operational 
within its functional specifications. The main activity of 
maintenance prcgramers is corrective in nature, commonly 
referred to as debugging. Tauseworthe considers enhancements 
as essentially changes to the specifications which enable 
the software to perform either a new task or a different but 
similar task. In each case the functional scope of the 
program changes. 

Swanson [Ref. 27] d isti nguisi es between three 
types of software maintenance; corrective maintenance, adap- 
tive maintenance and perfective maintenance. Corrective 
maintenance is performed in response to failures such as the 
abnormal termination of a program or tae failure to meet 
performance criteria. Adaptive maintenan ce is performed in 
response to changes in environments such as the installation 
of a new generation of system aardware. Perfective mainte- 
nance is performed to make the program a more perfect design 
implementation. For example to improve processing efficiency 
or to add new features. 

Other authors feel maintenance has only two 
basic components; modifications and enhancements. 
Modifications are any changes to existing functions to 
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correct bugs and meet specifications. Enhancements are addi- 
tions of new functions that were in the original design but 
never implemented or were added as a resuLt of an iteration 
of the development cycle [Bef. 25]. Modifications and 
enhancements will be the terms used in this thesis to refer 
to software maintenance. 

A more accurate and definitive model of the 
maintenance phase of the software life cycle and of che life 
cycle itself has been proposed by the Rone Air Development 
Center [Ref. 28]. Figure 2.3 illustrates two important 
items concerning this model. The first is that the process 
of software development is highly interactive (indicated by 
feedbaclc arrows) in order to incorporate new requirements 
and changes to software specifications. Secondly, and more 
important, it emphasizes the importance of the maintenance 
phase. The model indicates that maintenance phases are to go 
through the same iterative steps shown for software develop- 
ment, that is; analysis, specification, design, coding, 
validation, test and integration. 

b. Decommission Phase 

During this phase an assesmeat of the software 
is made to determine its further use, or to be replaced in 
its entirety. This may be due to compleceLy new requirements 
where it is considered more economical to replace the soft- 
ware then to modify the existing system or where procurement 
of new hardware dictates a new software system be developed. 



B. SOFTWARE HANAGEMEHT 



Software management is critical to the 
tion of a large software system. The 
managers of weapon system software proje 
difference between whether the final produ 



successful opera- 
decisions made by 
cts will mean the 
ct is maintainable 
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or non-nainrainable. Cave [Ref. 29] believes that: "Projecr 
failures are generally the result of improper or inexperi- 
enced management and not the lack of technical aoility.'* 
Cave concludes that the successful development of large 
software systems can be achieved in a consistant manner. 

In Cooper’s point of view T Ref. 30] a common stumbling 
block of software project management has been that manage- 
ment would always seek to optimize the development process 
in trying tc meet budget and scaedule constraints. This type 
of approach creates an initial design with little documenta- 
tion resulting in increased difficulty in maintaining the 
software and a corresponding increase in overall life cycle 
costs. 

While there is no step by step process which will guar- 
entee successful development of maintainable software, soma 
general policies may be stated that are quite helpful. Daly 
[Ref. 31] lists several items tiat have proved useful based 
on his experience in managing software developments. Table 
II provides a listing of two different approaches. Daley 
recommends Method 1 in order to produce a cost-effective, 
more maintainable software product. He also recommends the 
application of strict management objectives ro guide 
development. 

1. DOD H£n£2SSlS.Si E2l4si§2 

In December 1974 a DOD Software Steering committee 
was established with a goal of identifying critical weapon 
system software problems and to recommend policies for their 
solution . 

To support this committee the MIIRS corporation, in 
conjunction with John Hopkins University [Ref. 32,33] 
conducted a study of weapcn system software management. It 
was concluded that "...the najor contibuting factor to 
weapcn system problems is tie Lack or discipline ana 
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TABLE II 

Software Design Methods 



Method 1 



High level language 

Structured Coda 

Composite design(hierarchy 
of small segments) 

Parallel, top-down, botrom 
-up design all optimally 
used 

Simple data structures and 
work areas (nor) tightly 
packed 



Team approach to design 
(egoless programming) 

IBM’s structured walk- 
throuah for reviewing 
detail design and code 

Three separate teams, one 
design, one tests, one 
evaluates 

Complete set of hierarchy 
charts, sequence charts 
data maps and narratives, 
well commented listing 

Detailed rest plans for 
all tesx phases 

Program maintained by 30% 
senior programmers 



Only commercial 
documentation generated 
during develooment 



Strict management 
objectives established 
to auide development 



Method 2 



Assembly Language 
Tight Sonplex Code 
Large blobs of code 



Bottom-up design 



Tight, effecient, data 
structuces and work areas 
every bit used, no data 
uplicated) 

One prograa-One man 
concept 

No detailed technical 
review of design or ccdee 



Original coder tests, 
integrates and helps 
evaluate his program 

Detailed flow charts and 
general aacratives, no 
consistencv listing 
with comments 

No formal test plans 



Program maintained by 
inexpecienced programmers 
or technicians 

Extensive non-ccmmer cial 
technical memorandum 
generated and placed in 
library 

No management objectives 
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eagineering rigor applied to weapon, 
activities.” 

The software management steering committee incorpo- 
rated this and other ideas into a comprehensive plan to 
include policy, practices, procedures and technology initia- 
tives ' Bef. 34]. Parts of the plan are intended as 
supplements to principles stated in DDD Directives 5000.1 
and 5000.2. The first maintenance management policy states 
that "Ease of maintenance and modification will be a major 
consideration of the initial design.” 

Two techniques are used to provide management 
control to weapon system software. These are design reviews 
and configuration management. 

a. Design Reviews 

MZL-STD-1 521 (OSAF) annotates and describes the 
requirements for the following technical reviews and audits 
on computer programs: 

- Systems Requirements Review (5RR| 

- Systems Design Review (SDRi 

- Preliminary Design Review (?DR) 

- Critical Design Review (CDRi 

- Functional Confirmation Audit (FCA) 

- Physical Configuration Audit (P3A) 

- Formal Qualif icar ion Review (FQR) 

A software maintenance guideocolc [Ref. 35] provides a 
supplement to MIL-STD -15 2 1 . It describes ioems to be taken 
into consideration in order to oprimize rhe maintainability 
of software. For specific definitions on any of tne above 
items one is referred to standard. 
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b. Configuration Managsment 



Configuration managsment consists of configura- 
tion ii en tif ication , control, status accounting and 
auditing. 

As part of the proposed requirements assigned to 
contractors for the development of weapon system software, 
MIL-STD- 1679 , Weapon System Software Development, stares: 



The contractor shall establish and iraolemenc the 
disciplines of configuration management; namely configu- 
ration identification, configuration control, and 
configuration status accounting. The contractor shall be 
cognizant of the requirement for long-term life cycle 
support of the weapon system software. The approoriace 
degree of configuration management snail be applied to 
ensure completely accurate correlation between ‘descrip- 
tive documentation and the program in order to 
facilitate post-delivery maintenance by software support 
personnel. 



Configuration identification involves specifi- 
cally identifying and labeling the configuration items at 
selected baselines during the software life cycle. 
Baselines are reference points or plateaus in the develop- 
ment of a system; a baseline is formally defined at the end 
of each stage in the system life cycle. For example the 
functional baseline is typically the requirements specifica- 
tions document that outlines, in terms both the buyer and 
developer car. understand and agree to, exactly wnat the 
system will do. Configuration items are tie individual enti- 
ties that, together, define and describe the baseline. 
[Ref, 36] 

Configuration control provides the means to 
manage changes to the (software) configuration items and 
involves three basic ingredients; 

• Documentation (such as administrative forms and 
supporting technical and administrative material) icr 
formally precipitating aid defining a proposer cnange 
to a sortware system. 

• An organizational body for formally evaluating anu 
approving or disapproving a proposed cnange to a sort- 
ware system. 
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• Pi-3cedures for controlLiig the ao'ael changes to a 
sortware system. 

Software configuration status aocouating provides the 
mechanism for maintaining a record of how the software 
evolved and where the software is at any current stage of 
implementation. Software configuration auditing provides a 
means to determine how well the software product matches its 
associated documentation. [Ref. 36] 

DOD Directive 5303.29, Management of Computer 
Resources in Major Defense Systems, states: 

Defense system computer resources, including both 
computer hardware and computer software will be speci- 
fied and treated as configuration items. 

The primary objective of software configuration 
management is the effective management of a software 
system’s life cycle and its evolving conf igaration. 

Configuration is the final form, arrangement or design of 
the software [Ref. 36]. The importance of configuration 
management is that it gives one the ability to manage change 
during the development process. If a program maintenance 
manual is being designed in conjunction with and as a part 
of the software system development, then it should be placed 
under the discipline cf configuration management. Changes 
in the design and contents of the maintenance manual can be 
matched or directly linked to changes in the software 

system. This is the intent of DDD Directive 5000.29. 

2- OOD Directives and Standards 

Policies and procedures for acquisition of weapon 
system software are different in most respects from those 
used for procurring automated data processing eguipment 
(ADPS) . The distinction made between these two categories of 
automated systems is a direct result of the 1965 "Brooks 
Act" (Public Law 39-3C6,U0, O.S.C. 759). 
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The Office of Managemenr an Buiget (0MB) and the 
General Services Administration (GSA) adninister the Brooks 
Act guidelines. ADPE is controlled by tiiis Act and falls 
under the cognizance of tie Assistant Secrecary of 
Def ense(Controller) . Weapon system software, on the other 
hand, is excluded froh^ the provisions ot this Act and fall 
under the jurisdiction of the Office of tie Under Secretary 
of Defease for Research and Engineering. 

There is no centralized source of guidance with 
respect to weapon system software maintenance for DOD 
orga^zations to follow. There are many directives, regula- 
tions, specifications and standards that impact on weapon 
system software to varying degrees. The nost important ones 
are described here. 

a. Weapons Standard W3 8505 

WS 8506 is considered to be a comprehensive and 
very good specification for the documsntion of program 
development, particularly in view of its early publication 
date (1971). One of its strong points is: 

A strategy for making each level of documentation 
responsive to the next UDoer level (subproaram design 
under program design) which represents foresight in the 
use of toD-down design prior to the tine this term was 
in vogue [ Ref. 15]. 

It dees not include such programming techniques as struc- 
tured programming, but this technique was not developed at 
the time of its publication. 

Its weaknesses include a lack of change proce- 
dures, documentation standards for diagrams (such as 
Hierarchy Input/Output or HI?D) and regression testing 
[Ref. 15]. 
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b. MIL-STD-483 (USAP) 

MIL-STD-483 (USAF) Conf igur a t i on (lanagansnr for 
Systems, Equipment, Munitions, and SompacsrPrograras," 1 June 
1971, defines the entire spertrum of aotivites associated 
with controlling changes (a oritical need for maintenance 
work) to computer programs. 

c. HIL-S-527 79 (AD) 

MIL-S-52779 (AD) , "Software Quality Assurance 
Program Requirements," 5 April 1974, regaices that a Quality 
Assuranoe Program (QAP) be implemented specifically for the 
developaent of computer programs and related documentation. 
Even though this standard is concerned with the development 
phase, it is important because it can directly affect the 
quality of software documentation. 

d. SECNAVINST 3560. 1 

SECNAVINST 3560.1, "Department of the Navy 
Tactical Digital Systems Documentation Standards," 3 August 
1974, identifies, names and describes that set of documents 
necessary to supprt both the ievelopmenr and mainrenance of 
tactical software. A review of 3560.1 was conducted zo 
derermine how well this standard supports software mainte- 
nance ac*ivi-^y [Ref. 37]. As noted by this review there are 
some positive and negative aspects to tie standard. Some 
positive aspects include: 

- Applicable document statements. 

- Resource budgets (time, space) . 

- Numerous examples. 

- Content check lists. 

- Interface descriptions. 

- Test coverage. 

- Detailed Table of Contents for each specification. 
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The deficiencies oE the standard include a lack 
of requirements for the subject of traceanility , a need for 
increased emphasis on validation, and tie use of inconsis- 
tent or non-defined terminology. The review indicates the 
standard seems more orientated towards software development 
then to softwre maintenance. The review also notes the stan- 
dard's strong orientation towards the Sa/y's tactical data 
system. Scneidewind, [Bef. 37], recommends ”...a more 
general orientation might be preferable to achieve a wider 
applicability to a variety of software systems." 

e. DCD DIRECTIVE 5000. 29 

DOD DIRECTIVE 5000.29, "Management of Computer 
Resources in Major Defense Systems," 26 ipril 1976, estab- 
lishes DOD policy for the management and control of computer 
resources during system acquisition. .1 aintainability of 
software is called out as a major consideration during the 
initial design. It also directs that support items required 
for cost effective maintenance be specified as deliverable 
items. Documentation is listed and defined as a support 
item. 

f. MIL-STD-1521 (USAF) 

MIL-STD-1521 (OSAFi , "Technical Reviews and 
Audits for System, Equipment and Computer Programs," 1 June 
1976, prescribes the requirements for tne conduct of tech- 
nical reviews and audits in conjunction with the documents 
defined in MIL-STD-433. Direction is provided concerning the 
review and audit of computer program configuration items and 
their associated documentation. Each type of review or audit 
is described in an appendix to the standard and can serve as 
a basis for checking compliance with maintainability 
requirements. The documentation discussed here is related 
more toward system design reviews then towards the 
documentation of program listings. 
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g. DODINST 5000. 31 



DOD Instruction 5330.31, "latarim List of DOD 
Approved High Order Programming Languages (HOL) , " 24 
November 1976, specifies which HOL's are approved for use in 
conjunction with DOD Directive 5300.29. Although this 
instruction allows for certain exceptions, it attempts to 
reduce the proliferation of HOL's in defense systems by 
limiting new development to six approved languages: CHS-2, 

SPL-1, TACPOL, JOVIAL, COBOL, aid F3BTRAN. Its major impact 
is in the standardization of compilers and in preventing 
each DoD activity from developing its own unique programming 
language. 

h. MIL-STD-1679 (NAVY) 

MIL-STD-1 679 (NAVY) , "Weapon System Software 
Development," 1 December 1973, establishes uniform require- 
ments for the development of weapon system software within 
DOD. Strict adherence to the provisions of this standard 
will help ensure that the tactical software so developed 
will be improved over current versions of tactical software. 
MIL-STD-1679 includes developments in programming tech- 
nology, and management such as structured programming and 
design walkthroughs, which have occured since the release of 
WS 8506. It stipulates the use of high order languages and 
specifies the use of configuration management for corre- 
lating documentation with the program for maintenance 
purposes. [Ref. 15] 
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III. T ECH NIQOES TO SDPPOSr SOP! WARE DDCOMENT ATI3 H 



A. STROCTORED PROGHAHHIHG 



There are several definitions and goals of structured 
programming. Some of these goals relate to the design and 
testing of large software systems. One oarticualr goal of 
structured programming is to organize and discipline the 
program design and coding process in order to reduce logic 
type errors [Ref. 38]. It is generally accepted that the 
goals of structured programming incluie those of software 
engineering. In particular these goals are: modifiability, 

efficiency, reliability, and understandibility of the 
program code [Ref. 39]. 

What must be shown is how structured programming 
supports documentation. This is not easy to do because 
structured programming is not a universal and well defined 
concepr. It is defined in many places, [Ssf. 39,40,^2], but 
not always consisrant ly. However, its essence is fairly well 
understood. It is the pracrice of of programming using a 
limited but sufficient set of control consnructs Figures 3.1 
and 3.2 illustrate the five basic control constructs as 
reguired by MIL-5TD- 1 679 . 

Myers [Ref. 18] provides a List of seven basic elements 
of a structured program which should be applied zo help 
reduce program complexity and promote clarity of thought by 
the programmer. 

• The code is constructed from sequences of basic 
elements. 

• Use of the GOTO statement is avoided whenever possible. 



• The code is written in an acceptable style (e. g 
meaningful variable names, avoid statement 
avoid language tricks). 



. use 
ables , 



• The code 
breaks 



>rlv indented on the listing so that 
can oe easily followed 



is properly indented 
in execution* sequence 
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Sequence 



If-Ti sn-Else 



Process”! 



I” Process's” ( 
I I 



SEQUENCE 




Do-Whil 2 




DO WHILE 



Figure 3, 1 Basic Control Constructs. 
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with t hs 



(e. g. a DO statement taa be easily matched 
ENDDO statement ending ths loop). 

• There is only one point of entry and one point of exit 
in the code tor each module. 

• The code is physically segmented on the listing to 
enhance readibilty. The exeoutable statements for a 
module should fit on a single page of the listing. 

• The code represents a sinple and straightforward solu- 
tion to the problem. 

Figure 3.3 provides an example of strucrured and nnsrruc- 
tared coding. A structured program is structured in zvo 
different ways. First, it is structured with regard to flow 
of control and execution of the progran. Second, it is 
physically structured by the use of indenration. 

Another way of viewing struotured programming is to see 
it as rhose attributes of a program that contribute to the 
readibilty of its form. For example consider the develop- 
ment of a file management system. Obviously one required 
function of such a system would be the capability to search 
for a given file identified by a specific name. ^ Figure 3.U 
illustrates such a function as coded in the recently devel- 
oped DOD high order language ADA (see TSef. 4U ] for details 
on -he ADA language). As can be seen in Figure 3.4 struc- 
tured programming makes for a more readable and discernible 
sequence cf code. The main tenants of structured programming 
are displayed, that is; hierarchic relationships between the 
lines of code, a consistent indentation policy, and 

begin-end groupings which make it easier to follow the 
program flow. Comments are used extensivly to introduce 
each new module and structure. 

The results of structured programming are readily appa- 
rent with easy to read code and easy to follow logic flow. 
Functions and procedures are confined to discrete areas in 
the program listing. The objective is to make the cods, in a 
very meaningful and useful way, self - documenting , chus 

reducing the need for external documents describing the 



Do-OntlL 




DO UNTIL 



Cas* 




?5cess I 



Figure 3.2 Basic Control Constructs. 
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UNSTRIJCTU RED 



5 TRacrJSED 



label 

label 

label 

label 

label 

label 

label 

label 

label 

label 

label 

label 



IF p GOTD label q 
IF w GOTO label m 
L function 
GOTO label k 
m M function 
GOTO label Ic 
q IF g GOTO label t 
A function 
B function 
C function 

r IF NOT r GOTO label s 
D function 
GOTO label n 
s IF s GOTO label f 
E function 

V IF NOT V GOTO label < 
J function 

k K function 
END function 
f F function 
GOTO label V 
t IF t GOTO label a 
A function 
B function 
GOTO label w 
a A function 
B function 
G function 

u IF NOT u GOTO label w 
H function 
GOTO label u 
w IF NOT t GOTO label ^ 
I function 

V IF NOT 7 GOTO label k 
J function 

GOTO label k 



1 IF p THEN 

A Cinction 
B function 
2 IF g THEN 
3 IF t THEN 

G function 
4 DOWHILE u 
H function 
4 END DO 

I function 
3 (ELSE) 

3 5NDIF 
2 SL3E 

C function 
3 DOWHILE r 

D function 
3 ENDDO 
3 IF s THEN 

F function 
3 ELSE 

E function 
3 SNDIF 
2 ENOIF 
2 IF 7 THEN 

J function 
2 (ELSE) 

2 ENOIF 
1 ELSE 

2 IF 'rf THEN 

N function 
2 ELSE 

L function 
2 SNDIF 
1 ENDI? 

K fu notion 



I 






Figure 3.3 Structured 7s. Unstructured Coding, 



code. This has an effect on the design of 
called the Program Maintenance Manual and will 
in detail in Chapter IV. 



the document 
be discussed 
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function SEARCH (FILE NAME;KSI T?PE) return 

FILE INDEX IS ~ - 

begia 

— Look for the specifiei Key recori in the 

— specified file# returning the index of its 

— position 

for I in FILE^INDEX'FI RST. . FILE INDEX'LASI loop 
— Search the whole data base# from first to 
— last 

if FILE MAP(I) /= NJLL 
— Checlc data base for a null or a 
— match 

and then FILE MA?(I> = FILE NAME 
and then FILS"KE!f(I) = KSX TYPE then 
return (I) ; “ 

end if; 
end loop; 
raise BAD FILE; 

— Raise an exception if the desired record 
— IS not found 
end SEARCH; 



Figure 3.4 File Search Function. 

B. MODDLARIZATION 

Modules are the building blocks of software. Good 
modular programming usually requires that external inter- 
faces# such as input/output, be isolated inro seperare 
modules. Modular programming itself is the practice of 
implementing software in small, functionally orientated 
pieces. These pieces are usually implemented as subroutines, 
functions or clusters of functions. Each module is devoted 
to one or more tasks related *o a function; the module may 
be accessed from one or several places in the software 
system. 

Modularity is often defined in terms of properties poss- 
essed by ’’modular" systems. 

A program is modular if it is written in many relaoivelv 
inaependent parts or modules which have well denned 
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interfaces such that each [nodula makes no assumptions 
about the operation of other modules except what is 
contained in the interface soe cificatiois. 

Modularization , consists .of dividing ^ program inro 
subprograms (modules) which can be comoilea sepacatsly, 
but which have connections with othec nodules.. .A defi- 
nition of "good" modulacity must emphasize the 
requirement that modules be as disjoint as possible. 

Modular .programming is the organizing of a complete 
program into a number of small units. .. where there is a 
set of rules which controls the characteristics of these 
events. 

Modularity deals with how the structure of an object can 
make the attainment of some purpose easier. Modularity 
is purposeful structuring [Ref. 33]. 



There is a trend towards defining modules in terms of the 
number of lines of code they contain. Programming standards 
frequently contain a somewhat negative approach such as 
"...modules shall contain less than X lines of code." Some 
authors feel that the size aspect is not as important to a 
module as its functional aspect. In other words a small 
complex module may be more difficult to understand than a 
large well structured module. However, the majority still 
favor limiting module size, when possible, to less than 100 
lines of code in order to maintain modules as "discrete" 
entities and to aid comprehension [Sef. 39,40]. 

There are many advantages to using modules. Parnas 
[Ref, 24] argues that the most i rapcrtant aspect of modulari- 
zation is the ability to anticipate and design for changes. 
If the function of a module changes, that module alone has 
to change. If the need for a function arises during the 
design phase, a module with tais function can be invoked at 
the point of need. If an error in the program is found, the 
probability is that its correction will be limrted to one 
module. Once a module has been tested, and can be compiled 
seperately, it can be reliably used in different places in 
the program. [Ref. 41] 
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Sin-e modularization makes the structure of a program 
easier to understand while loralizi.ig functions and 
processes, the need for external documentation is again 
reduced. 

As a final note, there has to be a distinction made 
between modualrity and structured programming. 



This distinction is necessary because program structure 
is a relatively meaningless concept in' some programmino 
languaaes, such as plain vanilla assembly language (as 
opposed to assembler enhanced with strong macro capa- 
bility). In contrast, modularity is usable in all 
domains. Thus, the line between modularity and structure 
may be a tenuous one to walk, but it is an important 
one. Note that good modules may or may not possess good 
program structure and that bad modules may also possess 
pood program structure. The two subjects are discernable 



C. DATA STRDCTORE 

In some programming languages there are at leasx two 
ways of working with a string of bits or characters. Dne way 
is to declare the string as part of a structure (Figure 3.5) 
and then manipulate the string oy name; 

OTHER STRIN3 = CHARACTER STRING 



Structure DATA STRUCTURE; begin 

item CHAHlCTER STRING 5 characters; 
item OTHER VARIABLE 32 oits; 
end Structure; 



Figure 3.5 Example of a Data Structure. 
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A second method is to use a b/te manipulating function to 
define the desired string at every point of usage in the 
program: 



OTHER_STRING = BYTE ("H AR A3 TER_S T RI NG , 5) ; 



Suppose the character string named OTHER_srRING is utilized 
100 times in the program. I.i order to change the string 
format asing the first method (Figure 3.5t , only one easily 
identified line of cods has to change. In the second case 
there are 100 lines to change throughout the program. 

Languages may or may not support such data structuring. 
COBOL and PL/I provide elaborate data srractures for format- 
ting report data for printout. In addition such changes as 
stripping off leading zeros, inserting a decimal point, 
adding check protect characters, and inserting a leading 
dollar sign are easily accomplished. At the other extreme 
FORTRAN and BASIC offer no data structure capability beyond 
the array [Ref. 43]. 



Data structure impacts the areas of software design and 
software maintenance. One methodology, called the Jackson 
method * Ref. 45], stresses designing the program structure 
by first locking at the data structures. According to 
Jackson, an algorithmic structure is highly related to data 
structure; programs that obey data structure design will 
have a more maintainable program structure as well. 
Obviously different application areas ha/e different levels 
of need for data structure orientation. 

One of the noticable effects of large software systems 
is that algorithms end up transforming one data structure 



into another data structure. This results 
terms a "structure clash." The reason for 
commonly a proliferation of unnecessary code 
tured programming goals, or lack of design 
"clash" is a result of maintenance. 



in what Jackson 
this cccuring is 
, lack of struc- 



Sometimes 



the 

and 



corrective 



enhancement, where the changes have added information or 
changed the data structure to meet the carrent need. Two 
solutions have been proposed in this area. Grouping or 
"clustering" of data and abstract data typing [Ref. 43, 49]. 

Where a set of data declarations interrelate, either by 
function or by context, they should be grouped together for 
ease of understanding and modification into one block. This 
is the "clustering" ccncept. If a change is needed it can be 
isolated into one block. Only those modales which use than 
block of data need be recompiled. 

With the concept of abstract data typing, such as used 
by PASCIiL and ADA, (Ref. 44] all data must be explicitly 
declared to be of a particular type. Certain types are 
defined in the language, but these must be supplemented by 
programmer-defined types. Associated with a type is a set of 




type RECORD FORMAT 1 is 
record 

EMPLOYEE NAME: array(1..30| of CHARACTER; 
EMFLOYEE~RATS: float; 

SMPLOYSE~HOURS : integer range 0..99; 

FILE1 RECORD: RECORD FORMAT 1 



Figure 3.6 Example of an ADA Data Structure. 

legitimate values which objects of a type may assume and a 
set of operations which may be performed on that ~ype. 
Figures 3.5 and 3.6 show examples of ADA data structures. 

This kind of typing has three characteristics: (1) the 
properties of a type are defined centrally at the '^y?= 
declaraticn, and if they change they need only be changed in 
cne place; (2) only the abstract properties of a type need 
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bs known to reference data of chat type, >fith implementation 
derails “hidden” in the declaration; and (3) strong type 
matching may be enforced by the compiler, eliminating type 
mismatch errors as a reliab ilit y/maio tainability issue 
[Ref. 43,44]. 

As a final consideration, it is always important to name 
data effectively. Heaningful names are always preferable. 
EMPLOYEE_NAHE conveys far more information about the data 
value then EMFNAM. This supports the goal of readability and 
the ultimate goal of having the program be as self 
documenting as possible. 

D. DATA COHMUNICATION 

There are two basic types of daca comn un ication, inrra- 
program and inter-program. Intra-program data communication 
is essentially communication between modules. This can be 
accomplished by paramenter lists, global (or common) data 
and a recent concept called a data “cluster”. A cluster is 
where a constrained ” semiglobal' data base is shared among a 
limited number of processes or functions. [Ref. 42,43,44] 

A paramerer list idenrifies only chose data items and 
formal parameters used by each individual module. The 
preferred method of intra-program communication is by the 
use of a parameter list [Ref. 43]. The main advantage 
gained is that all data used by the module are identified 
and isolated. 1 ~ is not possible for the module to have a 
surprise effect on the code which invokes che module. 

Glooal variables are used for large guanticies or data 
when it is not convenient to specify suca a large paramerer 
list, at each point of call. dost auchors recommend minim- 
izing the use of global data for good modular and struccured 
programs. The reason for limiced use is that, a module may 
modify a global value whose original value was cricical to 
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the calling environment. This may lead to undesirable and 
untracable side effects. [Ref. 40,!42] 



k side effect is cne brought about other than via a 
parameter mechanism. It is generally oonsidered raiher 
undesirable to writs subprograms, espeoially functions, 
which have side effects. However, some side effects are 
beneficial. Any subprogram which performs input-output 
has a side effect on the file; a function delivering 
successive numbers of a ssqueice of random numbers only 
works because of its side effects: if one needs to count 
how many times a function is called then we use a side 
effect;, and so on. Care must be taken when using func- 
tions with side effects that the function does not cause 
errors in other sections of tie program. [Ref. 44] 



The cluster concept is an attempt to fulfill the need 
for global variables. A data oase and its family of manipu- 
lating procedures is isolated from the rest of the program. 
A program needing some or all of of the clustered data must 
explicitly import it. The cluster itself can distinguish 
between data and procedures which may be exported or not. 
The side effect problem is at least isolated and bounded. 
[Ref. 40,42] 

Inter- program data communication is provided either by 
passing data flags and blocks through ai operating system 
communication area, or by passing larger volumes of informa- 
tion on files. The UNIX concept of "pipes" in which 
predefined files are automatically passed from one program 
to the next is an example of this type of data 
communication. [Ref. 47] 

The proper use of data conn unic ation clarifies program 
flow and tracability of processes. This, of course, supports 
the maintenance programmer's task in the correction of 
program errors and in his understanding of the program's 
documentation. 
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HIGH ORDER LANGUAGES (HOL'SI 



High order languages are those computsr languages which 
are essentially machine (hardware) independent. This is in 
contrast to assembly languages that were designed for a 
particular hardware architecture. For example, the INTEL 
8080 assembly instruction set will not work at all on a 
Motorola 6800 based machine. In contrast a standard FORTRAN 
program can easily be used on any computer with an appro- 
piate FORTRAN compiler. 

High order languages tend to support the concepts just 
discussed (structured programming, modularity, data struc- 
ture, etc.) to varying degrees. FORTRAN offers modularity, 
but is limited for program structuring and has almost no 
capabilty for data structuring. COBOL has excellent, robust, 
capabilities for data structures. Other languages have their 
strong and weak points. [Ref. ^3] Examples of good HOL code 
may be found in several references ‘Ref. !»0,42]. 

Documentation is supported by High Order languages 
(HOL’s) if the language is readable. FORTRAN is limited in 
this respect because of its six character limit on data and 
variable names. Some HOL's, APL for example, provide nc 
readabilty at all. APL is very difficult to understand after 
it is written down, even by the person who designed the 
program. 

ADA, the new programming language developed by the 
Department of Defense, promises to offer the best support 
for just about all the major software engineering princi- 
ples. ADA is a large language since it addresses so many 
different issues. Some of the key goals of ADA are listed in 
Table III [Ref. 44]. 

The overall objective of the Department of Defense is to 
provide one standardized language for use in all tactical 
embedded systems. This can provide substantial economic 
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TABLE III 
Key Goals of !LDA 



R EADABILIT Y 

It IS recognized that professional pcoaranis are read 
mere of-en then they are written. It is important, 
therefore, to avord an over-terse notation such as 
A PL. 

STRONG TYPING 

This insures that each object has a clearly defined 
set of values and prevents confusion between logically 
distinct concepts. As a conseguence many errors are 
detected by the compiler which in otter languages 
would have led to an executable but incorrect program. 

PROGRAMHING-IN-THE-LARGE 

Mechanisms for encapsulation, seperate compilation, 
and library management are necessary for the writing 
of portable and maintainable programs of any size. 

EXCEPTION HANDLING 

It is a fact of life that programs of consequence 
are rarely correct. It is necessary to provide a 
means whereby a program can be constructed in a 
layered and partitioned way so that consequences 
of errors in one part can be contained. 

DATA AB STR ACTION 

Extra portability and maintainability can be obtained 
if the details or the representation of data can be 
kept seperate from the specification of the logical 
operations on the data. 

TASKI NG 

For many applications it is imoortant chat the 
program be conceived as a secies of oarallel 
activities rather than just as a single sequence 
of actions. Building agprooiate facilities into a 
lanaaage other than adaing chem on via calls to an 
operating system gives better portability and 
reliability. 

GilESIC UNITS 

In many cases the logic of part of a program is 
indeoendent of the tyoes of values being manipulated. 

A mechanism is thererore necessary for the creation 
of related pieces of program from a single template. 
This is particularly useful for the creation or 
libraries. 



benefits by reducing the number of different types of compi- 
lers needed. It also promotes familiarity by programmers and 
maintenance programmers. Improved program clarity and read- 
ability should also simplify the documentation. [Ref. 46] 

P. THE PROGRAM LISTIHG 

If the overall goal is to reduce the quantity and cost 
of documentation and improve its quality and usefulness to 
the maintenance programmer, then it is highly desirable that 
programs be made as self-documenting as possible. In this 
manner one can substantially reduce the necessity to main- 
tain multiple forms of documentation rapresanting the same 
logic. Many authors advocate such an approach through 
structured, well commented program listings. Myers [Ref. 18] 
St at es : 



Since we already have the code, why not let it serve as 
the logic documentation?... additional documentation 
such as a flowchart would be undesirable because it 
would be redundant with the code. Redandancy in anv rype 
of documentation should be avoided because it increases 
the chances of conflicts. Furthermore, unless care is 
oaken to update the documentation (which is more diffi- 
cult if the logic documencat ion is physically seosrated 
from the code), redundent documentation often becomes 
totally useless after the code is modified a few times. 



Slass [Ref. 43] also agrees with this point of view stating: 



The documents, when they do erist, are generally written 
to conform to a separate set of requirements which 
soecify what the software documentation is to contain, 
ill too frequently, these requiremeits provide for 
irrelevent or useless information that the mair.tainer 
really needs. So, in a real sense, the iccument| which 
is supposed to be a clarifyina piece of material, ends 
up obscuring the needed information. 

Because documentation is separate from the software 
product itself, it is also frequently out of date. 
Ideally, the document would oe a perfect reflection of 
the program. In actual fact, this is rarely, if ever, 
true. Tae documentation can cherfore be misleading. She 
in their riaht mind would attemot to ma'ce corrections to 
a program aft er . r eading only the program documentation 
ana not the listing? 
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This au'thor recommends tha haresy rhac the listing be 
rhe place where most software documentation is placed. 
Nearly every requirement for documantation describing a 
program can be met and in fact exceeded by requiring the 
same information in the listing. 

DOD, in general, supports this point of view and gives 
explicit direction for what constitutes a well commented 
program listing in MIL-STD-157 9. However, MIL-STD- 1679 , 
SECNAVINST 3560.1 and other directives require extensive, 
derailed, external documentation (i.e., other than the 
program listing) to he produced. One valid reason for this 
requirement is the need for extensive design reviews 
required by configuration management recnniques. A second 
reason is that, until the mid-1970'3 and the advenr of 
sofware engineering techniques as discussed in this chapter, 
the program listing did net convey a great deal of informa- 
tion. A large amount of English text was needed to explain 
the design and structure of tha software and its associated 
data bases. Even Glass admits that soma external documenta- 
tion will always be required to give an overview of the 
structure and the software's design history [ Bef . 43]. 

This "external” documentation is aimed at specific 
users. Operator's Manuals are meant to be read by operators. 
Soecificat ions are meant to be read by both customers (to 
give them the ability to determine that the problem being 
solved is the one they want solvedi ani designers. lest 
documents are meant to be read by customers, to determine 
that proper reliability techniques are employed, and 
testers. The main problem associated with external documen- 
tation is that it frequently becomes inaccurate and outdated 
as maintenance programmers make changes to the program code. 
For this reason maintenance programmers tend to relay more 
and more on the program listing as the software system g'=-ts 
older. 
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The listing is. of necessity, accurate, since it is the 
program in all real senses oE the weri. For the same 
reason. rt is complete. Thus the only accurate and 
current representation of a orogram, in today's tech- 
nology, is frequently the program listing. .. If the code 
IS changed- it is much more likely that the docunenta- 
t ion . w ill. be also. In addition, the explanations in the 
listing will also likely to be readable by the intended 
target audience, a programmer. They will also be in 
place where he needs most to find them. The accuracy and 
completeness attributes of the listing will also tend to 
appiy as well to the documentation. i,Ref. 43] 

The main line of thought being developed is that recent 
trends in programming technology, as presented in this 
chapter, have shifted the emphasis of programming documenta- 
tion from "external" documents to the program listing 
itself. A greater detail and quantity of information about 
the program is now directly available to the maintenance 
programmer. This has a significant impact on the way one 
should design documentation as a whole. Chapter IV will 
discuss this point of view as it applies to a specific docu- 
ment, the Programmer's Maintenance lanual, and how it should 
be designed. 

1. Com me nting 

It has bean stated that one objective to improve the 
doc ument axion of software was to make the program code 
itself more readable. Two techniques already discussed were 
sxructursd programming and the use of higa order languages. 
A third technique is the placing of comasnxs at appropiaxe 
places within the program code. One of the main advanxages 

of a consistant commenting policy is its independence from 
the programming language used. There are very few compilers 
xhax do not allow comments to be placed in the listing 
C Raf . 40 ]. 

A second advantage is that commenting closes the gap 
bexween computing managers and computer programmers. This 
gap develops because of xhe programmer's absolute meed for 
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attention to details. These details include such items as 
assembly language instruction choices, high order language 
statement type choices, flag initialization procedures, and 
the design of nested loops with if.. than constructs which 
implement the logic of the software system. The manager, on 
the other hand, must keep a "Big -Picture" perspective of the 
system and be able to evaluate an elusive entity called 
software quality. Software quality is often based on items 
such as reliabilty, readability and portablity [Ref. 38]. 
In order to evaluate all these "-ilities", the manager must 
be able to read the program listing and understand the 
implementation of the software design without necessarily 
being familiar with all the in’s and out's of a particular 
program language. 

Comments assist in putting more documentation into 
the program listing as well as making the program more read- 
ible. Comments explain details about the program that are 
not appearent from the code itself. Taole 17 provides a list 
of where comments should appear in the program. One DOD 
activity, the Marine Corp's Tactical Systems Support 
Activity, has had a great deal of success in easing its 
burden of software maintenance by implementing a detailed 
commenting policy. Although MCTSSA's programs are mainly 
written in the Navy's CMS-2 language, it was found tciat such 
a policy helped reduce the amoint of time spent by program- 
mers on software changes in addition to the time savings 
achieved by the use of a hign order language. [Ref. 48] 



49 



TABLE IV 

Recommended Locations for Coamants 



1. At the beginnning of aaoi tnodula, include tha 
module name, the currant date, the nodule's 
function, its inputs and ouxputs, its limitations 
and resxrictions, including assump; ions , its 
error processes, and the name of tha develooec. 
aajor modules should also include tha history 

of modifications: for each change, the date, 
the maintainer's name, prupose of tha change 
and scope. 

2. At each subfunction, whether it be a straight 
sequence of code or a logic branch or a begin- 
and block, an explanatioa of that subfunction. 

3. At each interface, a clear dafinition of xhe 
interface and a reference for further infor- 
naxicn about the other side of xhe interface 
(where possible). 

4. At each group of functionally or otherwise 
relaxed declarations, an explanation of the 
role and makeup of the group. 

5. At each declaration, an explanation of the role 
of the item and the meaning, if any, of its 
possible values. 

6. At each dif ficult-to-unde rstand program portion, 
an explanation of what the code does and why a 
complex solution was necessary. 
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IV. TOE MAINIESANCE mandal 



A. OBJECTIVES OF A MAINTENAHCE HANJ AL 

In order to determine hoi# a progcanmer’s maintenance 
manual should be organized it will be helpful to examine 
some specific goals that apply to any type of manual. 

1 . G ene ral 

The first objective is zo enumerate those general 
organizational qualities of writing and style that lead to 
ease of use and readibility of technical publications and 
documents. There are several factors that insure the infor- 
mation contained in a manual are is easy to use. These 
factors can be characterized into two broad areas. The first 
area concerns the concept than all information presented by 
the manual be easy to find or locate. The second area is the 
concept chat, once one finds the information, the informa- 
tion is readily understood. 

The factors that support ease in finding information 
are consistency, pointers and arrangement [Ref. 50]. 
Consistency is the principle that similar objects (i.e. 
maintenance manuals) containing the same information (how to 
understand and change a computer pcogrami be presented in 
identical ways. In ether words, all manuals should have 
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Pointers are essentia.1 signposts vfhich identify 
tslated groups of information. Pointers are represented by 
entities such as tables of contents, indexes and section 
headings of text. Pointers anaounce the presence and loca- 
tion of information within the body of the manual. 

Arrangement refers to the manner of presentation 
used throughout the manual. The arrangement anticipates ways 
in which readers might look for specific information. The 
subject of a manual might typically be arranged by alpheber- 
ical or chronological order. subject classification is 
another method. For a program maintenance manual, the 
arrangement might be related to the hierarchical design of 
the main functions and subfunctions of the program or no 
some external criteria. This criteria could be specified by 
documentation standards incorporated in directives. 

The factors that support ease of understanding are 
simplicity, concreteness and naturalness [Ref. 50]. 
Simplicity is the concept that a writer should use a vocabu- 
lary and writing style that suits the intended readers. 
Admittedly, cne assumes that any paricular person having the 
need -o read a maintenance manual can underscand fairly 
complex compositions. Still, the goal of simplicity is to 
keep the technical "verbage" to a minimum, while presenting 
a clear and logical flow of descriptive information. In 
addition, a dictionary or appendix should be included to 
supply definitions of any "buzzwords” for clarification and 
consistancy. 

Concreteness ensures that verbal descriptions are 
more specific than general. It also implies that examples, 
diagrams and pictures be provided for amplification and 
clarification. Fcr program maintenance maiuals the bast type 
of diagrams tc use has seen a long history of controversy. 
Hierarchy diagrams, flow charts, HI?3 charts, and 
NA SSI-SCNEIDERMAN charts, ancug others, have seen the most 
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usage 'Ref. 51], New developments such as structured 
program design languages (PDL'si , automated graphic packages 
and abstract data typing for the design process are now 
being used tc supplement verbal descriptions of the software 
[Ref. 49 ]. 

The concept of naturalness provides the reader with 
the unfolding of information in an ordered manner. It 
ensures that readers can verify they are on rhe right track 
and will ultimately find what they are looking for 

[Ref. 52]. 



2. Reco rd of Des iq n 



The second objective of the programmer’s maintenance 
manual is to provide programmers and management a record of 
the philosophy of design and historical development of the 
software. The manual must inclade a concrete representation 
of the software design as well. Glass ] Ref . 43] describes 
four categories of documents which could be included as part 
of a maintenance manual. 

• design notes 

Design notes explain how and why sections of the 
software evolved into their present stace. They should be 
prepared in some sort of sranaard format, filed chronoloai- 
cally and cross-indexed to the program code. They do hot 
have to be detailed but should provide a uood overview of 
the concepts supporting a particular design ' approach. 

• EIQBbEM EEPORTS 

Problem reports are records of problems encountered 
during the design process. They should describe the problem 
and its ultimate solution. They are eventually placed in a 
permanent historic file once the final design is fixed. They 
are extremely useful in isolatina errors that occur during 
system testing. 

Improvement reports are suggestions and collections 
of ideas held for future changes to be incocoorated into the 
software svstem. They can be major improvements or cosmetic 
only, k reason for doing this is to pass sound ideas of the 
desianers to the maintenance programmers. These ideas mav be 
helpful when addina enhancements as a result of changes in 
user's requirements. 
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• VERSION DESCRIPTION 



Version .descriptions 
describe tne modifications and 
release of. the software. Each 
complete list of the changes, 
a list of the problem reports 



the impact of the changes on 



are numbered changes that 
e nhacncemeits added to a new 
numbered change should have a 
where they were made and why, 
closed and a description of 
the users in the user's terms. 



The structure and description of the software system 
design is best kept as simple and straightforward as 
possible. Before the advent of structured programming and 
structured design tools (such as Program Design Languages) 
there was no standardized manner to represent the software 
design. This is still a problem today, especially when one 
desires to have "proofs of correctness" to determine that 
the software is free of errors [Ref. 49]. The best that can 
be done is to use a combination of items such as hierarch- 
ical block diagrams to list the major modules and their 
COP- 1 rol/data flow relationships, grouping of data item 
descriptions into "clusters" based on usage of the data, and 
coding the design with a well organizad, modularized and 
readable high order language. 



Support Maintenance P,i 21 £ammer.I_s Tasks 



The programmer's maintenance manial should be the 
single document that programmers need to refer to for sofi- 
ware maintenance activities. The manual has to be comolste 



in that it must contain all 
programmers to accomplish : 
correcting errors (modification! 
(enhancement) . 

To support, these tasks 
organized, concise and thorouga 
It must contain both an overall 
detailed procedure by procedure 
all data items inputed to the 
the processes performed on the 



the information needed by 
heir two primary tasks; 
and addi.ig new caoaoilities 

the manial should be a well 
description of the software. 

design view and a discrete, 
view. It has to describe all 
program (type/format/range), 
data, and the type/format/ 
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range of the output data. In a real-tias control systea 
where the software perforins coatrol functions based on the 
parelleL processing of data, the logical control responses 
to various data inputs must be specified. 

Data structure and organization las to be described 
in detail. Enumeration of data names, descriptions of 
tables and arrays and how they are used, initialized or 
otherwise manipulated by the program is of primary impor- 
tance. Cross-reference listings, which list each data item 
and every module, function and procedure where than data 
item is used, are valuable aides for understanding the 
program. 

Finally, two general guidelines must be kept in mind 
if the manual is to support the tasks of the maintenance 
programmer. First, The manual must provide for complete 
tracability from the user's operational reguirements to the 
actual program listing (lines of code) so that if a require- 
ment changes then the appropiate code can be correctly 
changed, deleted or new code added. Secoad, the manual must 
be easily modified and the change recorded properly in order 
to reflect the changes to the software. If this is not done 
the manual soon becomes outdated and useless as a mainte- 
nance ■^ocl. [Ref. 43 , 51 , 53 ] 

B. DEPARTMENT OF DEFENSE REQOraEMESrS 

How the objectives of a maintenance manual are best 
fulfilled is the main topic of this thesis. DoD currently 
requires a copy of the program listing and several 
supporting documents for representing the program design. 
Different DcD agencies have different requirements for docu- 
mentation and various names for individual documents. The 
DoD documents briefly described here are from the standard 
that describes a Program Maintenance Manual for all DoD 
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activities (DOD STANDARD 7935.13) aad tac 32 U.3. Navy stan- 
dards relating to software maiatenance docunentation. 

laaaal 

A description of the DoD requirenents for a program 
maintenance manual is presented in DDD STANDARD 7935. IS, 
•'Automated Data Systems Doc umentatLoa Standards," 13 
Seprember 1977. The standards main orientation is toward 
documenting larg* data processing systems, however, it can 
be used for imbedded tactical control systems as well. A 
copy of the format for the Program Maintenance Manual is 
provided in Appendix. A. 

According to the standard, the Maintenance Manual 
(PMM) is to be divided into four major sections. The first 
section is required to give a general description of the 
program; its purpose, history of develnpment, and define 
other documents used to support the program (User's Manual, 
etc.). The second section contains a system description to 
include applications, functions, input/output and informa- 
tion on summary reports. Details and characteristics of each 
procedure and subroutine taat would be of help to the 
maintenance programmer are to oe stated. Items such as data 
record types, table character! sites, exit and branching 
procedures, interfaces, descriptions of working and output 
files must be specified. The third section is to describe 
the operating environment to include what support software 
is needed. This section is also to contain a complete 
description of the data base as well as specifying the 
storage media for the data base (tape, disk, or internal). 
The fourth section is to contain information on specific 
maintenance procedures. This will include information on the 
labeling of functions, subroutines and data records, along 
with the programming standards utilized. This section is to 
contain a copy of the program listing itself. 
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2- £££2£^1 Descr ifition Docajient 

The Program Descriptioa Document (PDD) is required 
by SECN^VINST 3560.1. Its purpose is to provide a complete 
technical description of all procedures, functions, data 
structures, operating environment, operating constraints, 
and data base organization of the software system. The PDD 
is to describe and completely define the basic program logic 
and program procedures for eacn system control subroutine. 
The PDD is also required to be directly related to the 
program design specifications which are the formal func- 
tional requirements of the software system. The PDD is, in 
essence, the Navy's version of a DoD program maintenance 
manual. The PDD does not contain a copy of the program 
lisxing or a complete data base description. 

3. Data B as e Design Document 

The Dana Base Design Document (0BDD| is required by 
the same instruction to provide a complete detailed descrip- 
tion of ail common data items necessary to carry out the 
functions of the software system. Zoramon data is defined as 
that data required and used oy two or mors subprograms. 
Examples of common data include constants, indexes, flags, 
variables and tables. The DBDO is to be based on the func- 
tional or performance specifications. All terminology in the 
DBDD is to conform to the programming guidelines of the 
program design specification and the particular programming 
language employed. The DBDD has to give an organized, 
detailed description of all data objecxs to include such 
cha racte risixcs as purpose of tie data object, field name, 
size, numeric type (fixed point, floaring poinx) , range of 
values, initialized condition. A cross-reference listing of 
each common data item (table, flag, etc.) to each program or 
subprogram where i~ is used or set will be provided. 
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Program Pacjca^ Do cu ment 

The Program Package Do^umeat (PPD) is designed to 
consist of all the program material items such as card 
decks, magnetic tape, disk parks or printed listing of the 
software instructions. The PPD is to inrlude an eccor free 
listing of a compilation of the source program and any data 
which is necessary for the program to run properly. Examples 
of these data items wculd be adaption data, data fils cons- 
tants, set-up (initialization! data and program parameter 
val ues. 



5* Pr obl ems with D0DJ.S Regg ir ements 



The DoD approach, as standardized in DoD STANDARD 
7935. IS, SECNAVINST 3560.1, and HIL-STD-1 579 (Navy) are all 
based on the supposedly "good management practice" of having 
the maintenance documentation of a software system be a 
complete set of English text. Information concerning the 
program is compiled into volumes taat, in complex systems, 
can reach several feet in width. All tnis text information, 
as briefly outlined previously, gives a system overview, 
explains each item and structure in the sysrem's data base, 
shows control flow, data flow, module interfaces, and major 
functions. All this information, in and of itself, is usable 
by the maintenance programmer. However, placing it in 
seperate volumes is not the best way to present ic. This 
information is much more valuable to the programmers when 
integrated into the program listing. To reiterate: "... 

Dcoument at ion information about a software system belongs, 
in most cases, in the listing of the program itself." 
[Ref. 53] There are three key reasons why documentation, to 
the greatest extent possible, should be placed in the 
program listing. 
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The first raasoa is that pr^grannsrs tend to dislike 
writing documentation. They would much rather be writing 
code, which is what they do best and feel the most comfor- 
table with [Ref. 54]. If the documentation is an integral 
part of the listing then using readable data names, jotting 
down a few lines of comment to explain low a procedure or 
function works and structuring the code becomes a much 

easier task. The programmer is saved from the tedious 
paper-work drill of having to look up a separate program 
maintenance document, figure oun how it's organized and 
where the needed information is and then submit a change 
outlining what program modif ica tions or enhancements were 
made. The programmer can be nore productive by combining 
two steps into one by keeping both nhe documentation and 

program code up to date. Having the cods and documentation 

together can be used by managers as a motivation factor by 
demonstrating less work for the programmers in the long run. 
Other benefits can be shown' as in the case of using a 

programming ream to develop a large software project. Here 
the team can design the documentation as they design che 
structure of the software. This can eliminate nhe need for a 
ssperate team just to design and write the documentanion. 
The documentation design can be directly related to and 
supportive of the software design. 

The second reason for placing documentation in the 
lisring is to enhance managements span of control. As 
mentioned earlier, there is a large requirement for managers 
to keep a big-picture view and be sole to supervise, direct 
and track programmer's activities and progress while they 
are performing maintenance tasks. The documentation in the 
listing provides the means whereby a manager can evaluate 
changes to the software and its resultant quality. Managers 
would no longer be required to evaluate changes to the coda 
and it's associated documentation and rhen have to check to 
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make sure the docume rtat ion rhange cocractly reflects the 
code change. In essence it is desired to avoid a ’’double- 
entry bookkeeping” system where the documentation describes 
the software as the managers and programmers think it works, 
and the listing represents how the software actually works, 
[Sef. 53] 

The final reason is that a program maintenance 
manual must remain accurate and valid as long as the soft- 
ware system is useful. Program m ers must be able to guickly 
logically use the documentation to understand what a section 
of code is accomplishing and how it is doing so. Again, if 
user's requirements change, it is essential that the soft- 
ware be changed rapidly and in an error-free manner as 
possible. If a maintenance programmer cannot tell how the 
code is working, changes based on valid user needs, or for 
any other reason, will be difficult at best. 

C. 1 PROPOSED "IDEAL" HAINTENANCE SANOAL 

To overcome the difficulties with updating the documen- 
tation and ensure that the documentation is in a form than 
is readily usable by programmers and managers forces one to 
consider a revised format for a program maintenance manual. 
The manual contents presented here are based on the advan- 
tages inherent with the quality and detail than the DoD 
standards require and those advantages gained from incorpo- 
rating current software engineering prac:ices. The "Ideal” 
program maintnenace manual will be divided into four 
sections; (1) Overall Program Strucrure, (2) The Program 

Listing, (3) A Data Dictionary, and (4) Supplemental 

Appendices . 
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1 



• Overal l Pr og r am Structure 

The overall program structure should consist of 
words and pictures indicating how the satire systsm hangs 
together. A functional block diagram, which shows all major 
modules, procedures and functions is esssatial. This diagram 
represents the systsm structure, the execution order (if 
possible) and data flow. The section should contain a well 
organized index, logically arranged, which points the way to 
detail level documentation in the listing. The index should 
reflect the block diagram and the design of the system. The 
index should locate major data structures and data clusters 
within each module. This section should contain a written 
text introduction to the overall purpose and function of the 
software, the hardware configuration used for tests and 
evaluation prior to software delivery, and the target 
computer system (tactical or lata processing) the software 
is to run on. Each module of the program will be listed, a 
brief description of the module given and the functional 
relaticnships/interfaces with other modules completely 
annotated. 

Finally, the section should state the company 
responsible for the program design and development, the 
names of the chief programmer and members of his team and 
applicable references and standards used. These standards 
should include the program performance specifications, stan- 
dards for data objects, and the language programming 
standards. 

2- The Program Listing 

The computer program Listing is the single most 
important tool for software maintenance activities. The 
objective of the maintenance manual is to maximize the main- 
tainability aspect of the listing. In this regard clarity 
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and readibility are to be emphasized over efficiency. It is 
important that the p.rogram listing be clear, concise, struc- 
tured, well designed, modularized and straightforward. 
[Ref. 48] Each module should contain a description of what 
the module does and what procedures or functions are 
contained in the module. Each module should contain a 
section for data descriptions or declarations, global and 
local. Table, variable and flag declarations may be segre- 
gated and logically grouped. 

a. Physical Layout 

Good physical layout is defined as "...that 
property of a program listing which makes it capable of 
being read and understood by a programmer not familiar with 
the program." [Ref. 48] Good readibility nay be achieved by 
a variety of technigues, some of which are; seperation of 
logically related groups of code, seperation comments and 
code, blocking (by using lines of asterisks) lengthy 
comments, the appropiate use of blank lines, logical inden- 
tation and the lining up of begin-end, if-then/else pairs. 
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with kDk. [Ref. 38, 39, 42] 

b. Commenting and Naming 

The use of meaningful comments is of primary 
importance to increase understanding of the program. 
Comments should explain, amplify and supplement the listing 
rather then echo the code. For example: 

N = N + 1 --Increment N 



62 






-- A message has just been iaserted iaca the message 
-- queue. 

-- Increment Msg QUEUE Pointar so that it points to 
-- the location where ^he next message may be 
— inserted. 

Msg_3 UEUE_Poiater = Msg_Queue_Pointer ^ 1 



Figure 4.1 An Example of Meaningful Comments. 

does nothing to explain why N is being incremented. A better 
example is illustrated by Figure 4.1 . 

If a program module consists of more chan one 
procedure or function then there should be commentary for 
each procedure or function. The comments for each procedure 
and function should contain an extensive, detailed descrip- 
tion of how the procedure operates and its purpose in the 
module. The sequence of processing should be described in 
chronological order to include the calling sequence of 
control. The hierarchical structure of the module can be 
reflected in a like manner as comments follow the physical 
indentation. Table III lists other criteria for commenting 
as discussed earlier. 

All names for data objects, nodules and proce- 
dures must be descriptive in nature. They should attempt to 
embody the character! sites of the data item -hey represent. 
Names such as ID_3ufier, SINE_Fu ncti on and ? AI_Roll_3UM have 



inherent 


meanings and are easier for 


the 


progra 


mmer to 


rrace 


through 


the listing. Names such as A, 


X, 


N , or 


XYZ are 


mean- 


inqless. 


Related data items and 


proc 


edures 


should 


have 


related 


names which demonstrate t 


heir 


interconnect 


ions. 



[Ref. 43, 44, 48] 
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c. Data Declarations and Dsfinitions 



All data items shaald be grained and organized 
according to their logical usage. Global data elements 
should be defined in one locatian. Local data elements are 
to described in the procedure where they are manipulated. 
The technique of information hiiing, where the structure and 
characteristics of local data aid parameters are unknown to 
procedures in other modules [Ref. 2'4 ], is to be utilized to 
the maximum extent. 

If the programming language does not support 
strong data typing for data declarations, as in the DoD high 
order language ADA, then variable, table, array and other 
data declarations must contain meaningful comments. These 
comments are to describe the purpose, initial value, range 
and distinct structure of each data element. Figure 4.2 
reveals how a data table (or record) would be declared in 



type MONTH NAME is (JAN, F 5B,MAS, APR , MAY, JUN, 

JUL,AUG,3E?,DCr,N0V,DEC) ; 



type DATE is 
record 

DAY: INTEGER range 1. .31; 
MONTH; MONTH NAME 
YEAR; INTEGER 
end record; 




Figure 4.2 Example of an ADA Data Table (Record) . 

ADA. The table is called 'DATE’ and has three components 
named 'DAY’, 'MONTH', and 'YEAR'. DAY and YEAR are defined 
to be of type INTEGER. MONTH has a sepsrate type declara- 
tion called MONTH NAME. INTEGER is assumed to be defined bv 
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the support software of the system and having the mathemat- 
ical characteristics of all integer numbers. Variables and 
constants associated with the table 3!VrE can then be 






Comment 

TABLE ACCOONTS 

~ -- Used to store information on 400 Bank 
accounts. Consists of four elements. 

1. ACCOUNT NAME (ACCTN AMSI 

-- Contains up to 40 ASCII characters. 

2. ACCOUNT NUMBER (ACCTNEI 

— Ranges form Zero to 9999 and is of 
numeric type INIESER. 

3. BALANCE (BALANCE) 

-- Ranges form -9999.99 to 9999.99 
dollars and is of numeric type 
REAL. 

4. FLA3 (ACTIVE) 

-- When True (=1), Account is in use. 
When Falsa (=0)/ Account is not in 
use. Is of logical type BOOLEAN. 

Misce lla ne ous 

Jt^program initialization tine the 
entire table is flushed (sec to ZERO). 
Indices (or oointers) related to this 
table are the named variables LASTACCT, 
NEXTACCT and NEWACCT. 5 

TABLE ACCOUNTS V DENSE 400 S 
FIELD ACCTNAME H 20 S 

FIELD ACCTNR I 14 S 

FIELD BALANCE A 22 S 7 5 

FIELD ACTIVE B S 

END-TABLE ACCOUNTS 






Figure 4,3 Example of a C3S-2 Data Table. 

defined. An example would be a variable named 'D' belonging 
to type DATE. Before D is used or initialized it must be 
further defined. This is dona by by denoting D with a dot 
followed by the component name as in: (D.DAI:= 4;) 

(D.MONTH:= JUL;), and (D.YEAR:= 1775). It is clear that ai 
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the attributes of the table railed DATE ace readily apparent 
TO the maintenance programmer. The reaiinility of earh data 
object clarifies the purpose and structure of the table. 
[Ref. 44] Figure 4.3 gives aa example of a common way zo 
declare a table using the Navy's CM3-2 programming language. 
The use of clear and concise comments fulfills similar 
objectives as data typing in ADA. 

3* A D icti onary 

A data dictionary provides descriptions of indivi- 
dual data entities and can be used as an index as to where 
the data elements are declared in the program listing. This 
is extremely useful for large programs, i.e., greater than 
10,000 lines of code. The data dictionary can and should 
provide the formats for the declaration of data within the 
program while being a catalog of the data resources of a 
software system. [Ref. 55] 

The data dictionary defines the logical organization 
and physical organization of tie system's data entities. The 
logical organization specifies requirements for data access, 
modificaxion, associativity and orher sysrem orientated 
concerns. The physical organization defines file smctures, 
record formats, hardware dependent processing features and 
database management characrerist ics. All data structures and 
the operations that are to be performed on each structure 
should be identified in the dictionary. The program listing 
can be referenced for details on data elements and those 
functions or operations dependent on these elements. A data 
dictionary can explicitly represent the relationships among 
data and the constraints these elements place on data 
structures. Algorithms that may take advantage of specific 
data relationships can be more easily designed and modified 
if a dictionary- like data specification exists. [Ref. 56] 
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It is appropiate that the data dictionary reflect 
the structure of the program listing as closely as possible. 
The concept of ’’mapping" the dictionary onto the listing 
ensures the consistancy required by maintenance actions. It 
is critical to the maintenance programmer to know which data 
items effect which particular modules and vice versa. A 
carefully designed and integrated data dictionary is an 
essential tool for any modifications or enhancements to the 
software . 

'*• Ap pen dic es 

This section of the maintenance manual is to contain 
that supplementary information which is of a historical 
nature. Examples would be notes on the development of the 
software design, problem reports and improvement reports as 
described by Glass [Bef* 43]. In a separata appendix could 
be a complete description of the intended operating environ- 
ment, hardware configuration and operating system support 
desired or required. A continuous file of each version 
release and a log of all changes made to the program (who 
made them and for what reason! should be included. 
[Ref. 40, 42, 48] 

A final appendix should contain a set of standards 
for commenting, algorithmic structures, and the data 
dictionary. The standards for commenting are useful for 
consistancy and to enforce readioility of the Listing. 
Standard algorithmic structures provide a framework for the 
development of module libraries. Such libraries can be 
utilized to add enhancements to the program in a short 
period of time since the modules involved are already tested 
for error free operation and the functions or services 
provided by the module are well known. Standards for the 
data dictionary provide common interfaces between the 
har dware/s oftwar 6 system and the user organization. This is 
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accomplished by specifying the flow and storage locations of 
data entities within the organization or rfithin the computer 
installation [Ref. 55]. Standards for a iata dictionary can 
also provide a library of standardized data structure temp- 
lates to be used for representing the Logical and physical 
characteristics of data entities within the software system 
database [Ref. 56]. 
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V. CONCLKIpNS &ND RECOMMEN D& IIONS 



The Department of Defense has an urgsnt requirement to 
reduce the costs of software maintenance during the coming 
decade. Recent advancements in the methods of software 
engineering such as modularization, structured design, 
structured programming and data abstraction have contributed 
to greater program comprehension. This increased comprehen- 
sion leads to easier modifications to meet a dynamically 
changing environment. 

It is the opinion of this author that the benefits 
obtained from proven software engineering practices can be 
realized in the program maintenance manaal. These principles 
can and should be applied to the design and standards for 
such a manual. The information availabls strickly from the 
program code itself forces us to question the practice of 
keeping the documentation seperate from the code, and leads 
to the conclusion that it should not be seperate but 
integrated into the listing. 

With this in mind the following recommendations are put 
forth; 

• The present standards for software documenrat ion be 
revised to incorporate the most aseful aspects of 
recent software engineering technology. 

• Studies should be undertacen with the goal of standard- 
izing ■*‘er minolo gy for software maintenance documents 
among all DoD activities. 

• A framework has been proposed for a orcgram maintenance 
manual. This framework shonld ba implemenred and 
■eszed on various size and typss of software systems lo 
discover what savings in "time and money can be 
ach ieved. 



69 



APPENDIX A 

PROGRAM MAINTENANCE MANUAL (DOD) 



from: DOD STANDARD 7935. IS, "Automatad Data Systems 

Documentation Standards,” 13 Ssotembsr 1977 



r' 



PROGRAM MAINTENANCS MANUAL 
TABLE OP CONTENTS 



Page 



SECTION 



1. GENERAL DESCRIPTION 

1.1 Purpose of the Program Maintenance 
Manu al 

1.2 Project References 

1.3 Terms and Abbreviations 



1 

1 

1 

1 



SECTION 



2. SYSTEM DESCRIPTION 

2.1 System Application 

2.2 Security and Privacy 

2*. 3 General Description 

2.4 Program DescriDtion 



2 

2 

2 

2 

2 



SECTION 



3. ENVIRONMENT 

3.1 Equipment Environment 

3.2 Support Software 

3.3 Data Base 

3.3.1 General Characteristics 

3.3.2 Organization and Detailed 
Description 



5 

5 

5 

5 

5 

5 



SECTION 4. PROGRAM MAINTENANCE PROCEDURES 

4 . 1 Con V entions 

4.2 Verification Procedures 

4.3 Error Conditions 

4.4 Special Maintenance Procedures 

4.5 Special Maintenance Pronraois 

4.6 Listings 



7 

7 

7 

7 

7 

7 

8 



L— 






70 



W W W O U W w M r-|CXfCf t/J 



r— 



SECTION 1. GENERAL DESCRIPTION 

1.1 Purgose of the Program )1 ainteraaoe Manual. This 
paragraph snail descfiBi EHe purpose or” the MM 
(Program Maintenance Manual) in the EallDwing words or 
apprapiate modifications thereto: 



The objective for writing this Program 
Maintenance Manual for (Project Nane) (Project 
Number) is to provide tie maintenaace programmer 
personnel with the information necessary to 
effectively maintain the system. 



1.2 Project Rsfsre 
a Srief summary~o 
history and devel 
nature of the sys 
war-gaming, manag 
hall be specified 
hall include its 
hail be the proi 
perating center ( 
omputer programs 
hall be included 
pecified, when 
efer ence number. 



s paragrao 
rences .app 



. cal, 



inve 



ness. Thi 

T"? Ee ref e 

opment of the project 
tern (tacti“’ 
ement infor 
. A brief i 
purpose a 
ect sponsor 
£) that 
. A list 
At least 



applicable, 
title and s 



matron. = 
escriptioa 
nd uses. 

and user 
will run 
of applic 
the foil 
by aut 
ecurity cL 



h shall provide 
licable to the 
. The general 
ntory concrol, 
tc. ) developed 
of this system 
Also indicated 
as well as the 
the completed 
able documents 
owing shall be 
hor or source, 
assification ; 



a. Users Manual. 

b. Computer Operation Manual. 

c. Other pertinent documentation on the 
pro ject. 



.3 Terms and Abb reviations. 
roviae a list of include “in 
efinitions or acronyms unigue 
ubject to interpretation by the user 
This list will not include item names 



This oaragraph shall 
an appendix any teemsj 
this document ana 
of the document, 
or data codes. 



to 



I 



1 



—j 
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SECTION 2. SYSTEM DESCRIPTION 



2.1 SYsxem A pp lic 
xhe Euncxions I'E 
cular application 
conxcol mission 
inputs (status 
extracting items 
data in order t 
specific mission 
These functions 
Specific Per forma 
Funcxions, of the 



a^on. The 
performs sha 
system, for 
activities 
reports, 
of data, aa 
o produce b 
ana informat 
shall be re 
nee Require 
FD (FunctiD 



purpose of the system and 
ll be explained. A parti- 
example, night serve xo 
accepting specific 
emergenc/ conditions) , 
d deriving other items or 
oth information about a 
ion for summary reports, 
lated to paragraphs 3. 1, 
ments, ana 3.2, System 
nal Description). 



2.2 Se cur ity 
descrioe xHe 



and Privacy. This oaragraph shall 
classlf il3"con pone nts of the system, 
including inputs, outputs, data bases, and computer 
programs. It will also prescribe any privacy restric- 
tions associated with the use of the data. 

2.3 Seneral Description. This paragraph will provide 
a compfeEensive“3'e scription of tae system , subsystem, 
jobs, etc. in terms of their overall functions. This 
description will be accompanied by a chart showing the 
interrelationships of tne major components of the 
system. 



2.U Program Descr 
grap5“is xo supply 
program and subro 
maintenance progra 
its relationship t 
nance programs re 
documenteu will 
Special Maintenanc 
initially contain 
discussed, foilowe 
program and its re 
paragraphs start 
Information to be 
tion is represente 



Ip t ion. 
details a 
utine that 
mmer unde 
o other p 
lated to 
be discuss 
e procedur 
a list 
d by a oar 
spective 
ing with 
included 
d by the f 



The puroose 
ad caaracte 
would be 
r standing t 
rograms. ( 
the specif! 
ad under 
es.) This 
of all p 
rative desc 
s ubroutinas 
2.4.1 

in the nar 
allowing it 



Identification - program number 
including a desiqnation of the y 
number of the program. 



of this para- 
ristics of each 
of value to a 
he program and 
Special mainte- 
c svstem being 
paragraph 4.4, 
paragraph will 
roarams ’ xo be 
ription of each 
under seperaxe 
trough 2.'4.n. 
rative descrip- 
ems; 

or tag 
ersion 



b. Functions - description of prooram functions 
and method used in the program'to accomolish 
the function. 

c. Input - description of the input. Descriptions 
here must include all informacion pertinent to 
maintenance programming. Including: 

(1) Data records used by the program during 
opera t ion 

(2) Input data type and location (s) used by 
the program when its operation beains. 

(3) Entry requirements concerning the' 
initiation of the program. 
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i. Processing - description of the processing 
performed by the program, incLuiing: 

(1) Major operations - the major operations of 
program will be lescribed. The description 
may reference chart (s) which may be 
included in an appendix. This cnart will 
show the general logical flew of 
operations, such as read an input, 
access a data record, major decision, and 

g rint an output which would be represented 
y segments or subprograms within the 
program. Reference may be made to included 
charts that present each major operation 
in more detail. 

(2) Major branching conditions provided in 
the program. 

(3) Restrictions that have been designed into 
the system with respect to the operation 
of this program, or any limitations on 
the use of the program. 

(4) Exit reguirements concerning termination 
of the operation of the program. 

(5) Communications or linkage to the next 
logical program (operational, control) . 

(6) Output data type and location (s) 
produced by the program for use by 
related processing segments of the 
system . 

(7) Storage - Specify the amount and type of 
storage required to use the program and 
the broad parameters of the storage 
locations needed. 

e. Output - description of the outputs produced 
by xhe program, while this description may 
reference output described in tae Users Manual, 
any intermediate output, working files, etc. 
should be described cor the benefit of the 
maintenance programmer. 

f. Interfaces - description of the interfaces to 
from this program. 

g. Tables and Items - provide details and 

characteristics of the tables and items within 
each program. Items not part of a table must 
be listed seoerately. Items contained within 
a table may be referenced from the table 
descriptions. If the data descriotion of the 
program provides sufficient information, the 
program listing may be referenced to provide 
some of the necessary information. At least 
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the following will bs included for each table; 

(1) Table tag, lable or symbolic name. 

(2) Full name and purpose of the table. 

(3) Other prograus that use this table. 

(4) Logical divisions within the table 
(internal table blocks or parts - not 
sn"trl.0s) • 

(5) Basic table structure (fixed or variable 
length, fixed or varianle entry 
structure) . 

(6) Table layout ( a graphic ocesentation 
should be used). Included' in supoorting 
description should be table controlling 
information^ details of the structure of 
each type or entry, unique or significant 
characteristics of the use of the table, 
and information about the names and 
locations of items within the table. 

(7) Items - the teen "item" refers to a 
specific category of detailed information 
that is coded for direct and immediate 
manipulation by a program. Used in this 
sense, the definition of an item is 
machine- and program-oriented rather 
than operationally oriented. Of primary 
importance is an explanation of the use 
of each item. At least the following 
will be included for each item; 



Item tag or label and full name. 
Purpose of the item. 

Item coding, depending upon the 
item type, such'as integer, 
symbolic, status, etc. 



h. Unique Run Features - description of any 
unique features of tie running of this 
roqram that are not included ii the 
omputer Operation Manual. 
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SECTION 3. ENVIRONMENT 



3-1 Eg vironmegt. This 

niscuss ^e“ equlpaeg^ conf ig uratiog 
characteristics as they apply to the 



oaragraph shall 
aad its geasral 
system. 



3,2 Support Sof^are. This 
various support so^ware usei 
tify the versiog or release 
system was developed. 



paragraph shall list the 
by the system agd iieg- 
number igder which the 



3,3 Data Base. Informatiog in this 
include a “complete description of 
consent of each data base used by the 



paragraph shall 
the nature and 
system. 



3.3.1 General Characteristics. Pro/ide a general 
description ol f Se“cEaractec Isti cs of the data base, 
including : 



a . 




programs utilizing tae compt..^..^ 
the use of the component in the system. 



b. Permanency - note whether the component 
contains static data that a program can 
reference, but may not change, or dynamic 
data that can be changed or updated during 
system operation. Indicate whether the change 
is periodic or random as a function of input 
data , 



c. Storage - specify the storage media for the 
data case (e.g, tape, disk, internal storage) 
and the amount of storage required. 

i. Restrictions - explain why limitations on 
the use of this conpoient by the program in 
the system. 

3.3.2 Organization and Detailed Description. This 
paragraph will serve“Io lefine Ehe Infernal structure 
of the data base. A layout will be shown and its 
composition, such as records and tables, will be 
explained. If available, computer generated or other 
listings af this detailed information may be refer- 
enced or included herein. The following items indicate 
the tyoe ox information desired: 



a. Layout - show the structure of the data base 
including record and items. 

b. Sections - note whether toe physical record 
is a logical record or one of several that 
constitute a loaical record. lientify the 
record parts, such as header or control 
segments and the body of the record. 

5 
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c. Fields - identify ea^h field in the record 
structure and, if necessary, explain its ourpose. 
Include for each field tie fnllowiig items: 

(1) Tags/labels - indicate the tag or label 
assigned to reference each field. 

(2) Size - indicate the length and number of 
bits/characters that maice up each data 
field. 

(3) Eange - indicate the range of acceptable 
values for the field entry. 

a. Expansion - note provisions, if any, for 

adding additional data fields to the record. 
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SECTION 4. PROGRAM MAINTENANCE PR0CED03ES 

Section 4 of the manual shall provide information on 
the specific procedures necessary for the programmer 
to maintain the programs that make up the system. 

4.1 Conventions. This paragraph will explain all 
rules; scSemesJ and conventions that have been used 
within the system. Information of tais nature could 
include the rollowing items. 

a. Design of mnemonic identifiers and their 
application to the tagging or labeling of 
programs, subroutines, records, data fields, 
storage areas, etc. 

b. Procedures and standards for charts, listings, 
serialization of cards, abbreviations used in 
statements and remarks, and symbols appearing 
in charts and listings. 

c. The appropiate standards, fully identified, 
may be referenced in lieu of a detailed ouiine 
of conventions. 

d. Standard data elements and related features. 

4.2 Veri ficat ion Procedures. This paragraph will 
inclu3e~rEose requifemenrs“and procedures necessary to 
check the performance of a program section following 
its s odif ication. Included may also be procedures for 
nhe periodic verification of the program. 

4.3 Error Condinio ns. A description of error condi- 
EionsT” non previously documen-ed, may also be 
included. This description shall include an explana- 
tion of the source of the error and recommended 
methods to correct it. 

4.4 Soecial Maint^ance Procedures. This paragraph 
shalI“cor.-cain any special procedures required which 
have not been delineated elsewhere in this section. 
Specific information that may be appropiate for 
presentation shall include: 

a. Requirements, porcsdures, and verification 
which may be necessary to maintain the system 
input-output components, such as the data 
base. 

b. Requirements, procedures, and verification 
methods necessary to oerform a Library 
Maintenance System run. 

it*5 Special Maintenance Programs. This paragraph 
shall cdntain“an Inventory“of any soecial orograms 
(such as file restoration, purging historical files) 
used to maintain the system. The se ' pro grams should be 
described in the same manner as those described in 
paragraphs 2.3 and 2.4 of the MM. 
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a, Input-Out p ut Re g uiraa ents . 

IncluaeaTn*" tnis paragraph shall oe the rsauire- 
ments concerning the equipment and materials needed to 
support the necessary maintenance tasks. Materials 
may, for example, include card decks for loading a 
maintenance program and the inputs which represent the 
changes to be made. When a support system is being 
used, this paragraph should reference the appropiate 
manual. 



b. Pro cedures 
The procedures, presented in a step-by-step manner 
hall detail the method of preparing tae inputs, sue 






s structuring and sequencing of inputs. The ooera- 
ions or steps to be followed in setting up — ---- 
nd terminating the maintenance task on th 
hall be given. 



, running, 
e equipment 



.6 Listings. This paragraph will contain or provide 
reference" to the location of the program listing. 
Comments appropiate to particular instructions shall 
be made if necessary to understand and follow the 
listing . 




3 



j 



73 



LIST OP EEFEREWCES 



1 . 



2 . 

3. 

4. 

5. 



6 . 

7. 



8 . 

9. 

10 . 
11 . 



12 . 



Halted States Governaeit Ascouatlag Office Report 
AFMD-81-25, Fed^al A 2 enries|_ Maiataiaeace of Computer 
Pro grams ; S3c p i ns ive~and~J ndec ma Dadedr p.“ T, FIBruafy 



Brooks, F.F. Jr. , 
Addison-Wessely , 1975. 



Ilii SZthical d^a^Month, 



Boehm, B. , "Software aai Its Imoa:t: A Quantitative 

Assessment," Datamation, v. 19, no. 5, pp. 48-59, May 
1973. 

Defense Science Board, Regort of the Task Force on 
Technology Based Str at aqy7~P.~^1, ~OoEo5’er~T?75r 

Kline, N. B. , and Scaeidewind, H.F., "Life Cycle 
Comparisions of Hardware and Software 

Maintainability," Third Natoial Reliability 

Conference . pp . 4a/3/1-T?7”T581 . ~ 

Lehman, J. H., "How Software Projects are Really 
Managea,” Datamation, v. 25, op. 113-12S, 1979. 

Leintz, B.P., Swanson, B. E. , and Tompkins, G.E., 
"C haract er istxcs of Application Software Maintenance," 
Communications of the'ACM, v. 21, no. 6, op. 466-471, 
T?7ET 



Munson, 

Practical Concern 
54-59, 1978. 



John B. , "Software Maintainability: 1 

for Lifecycle Costs," COMP3AC, pp. 



Cheatam, Thomas E., The High 7osts of Soft 
Nationax Technical Information Service , “1 973. 



rt war e. 



Lyons, Michael J., "Salvaging lour Software Asset 
(Tools Based Maintenance)," AFIPS, pp. 337-341, 1931 . 

Mills, H.D., "On the Statistical Validation of 

Computer Programs," Proceedings of the Second 

Interaticnal Ccnference"" cn““9ortwafe Engineering, 

0cto5ef“TI-T5,"pp7"-2B=J7, 1975. 



Reutter, John, III, "Maintenance is a Managemer.' 
Problem and a Programmer's Opportunity," AFIPS, op, 
343-347, 1981. 



79 



DsRcze, B. , and Nyman, T. , "The Software Life Cycle - 
A Management and Technological Challenge in the 
Department of Defense," IEEE Transictions on Software 
Engineering, SE-4, no, U7"pp. 3(79=3T3, only T973. “ 



Yau, Stephan S. , and Collofello, James S. , "Some 
Stability Measures for Software Maintenance," IEEE 
Transactions on Software Bnqinserini, v, 6, no. 6,~pp7 
5^5-5527"T750r ^ 



Naval Postgraduate School Technical Report 
NPS-54-82-002. Software Maintenance Improvement 
Through Befct^ “Development Sfandafas "End 
Documentation7~ by “Sen elde wind, N.777” Naval 
Postgraduate School, Monterey, CA, pp. 23-26, February 
1982. 



Pilcher, Russell D. , Technijuee Available For 
Improving the Maintainability oc“~DDD ^eagon "System 
Software, H.S. TEesrs7~~Haval “Poitgraauate School, 
HSnterey, California, June 1930, p. 9-10. 



DeRoze, B, C. , Special Presentation, Proceedings on 
Managino the Development “of 7eaponl” Syst9ffls“P5f tware 
Coni ere nee ,“pp 7“?- 2 -“7-T2 , Hay“T97S. “ “ 



Myers, G. J. , Software Reliabilitv Princioles and 
Eisctices, John wiTey'S'So ns7"*TP77 7 " 



Leintz, B, P. , and Swanson, E.B. , Software Maintenance 
Ma na gem ent . Add iscn-Wesle y , Reading" Sa7, T9SD. 



Silbey, Valdur, "Documentation Standardization," Data 
Ma nagement , v. 17, no. 4, pp. 32-35, April 1979. 



National Bureau of Standards 



Computer Software 
fanagement and “Uua 
T“TtJ, duly TS77. ““ 



Management - 
I=2i dontfol. 



Reoort NBS-3P-500-11 
A ?rimer For Pronect 
~by D727 7ife7 ??7 



Boehm, D. g. , "Software Engineering," IEEE 
Transactions on Computers, v, C-25, No. 12, Decemoef 

TS7S7 



Riche, Robert S., and 'williams, Charles S., A Software 
Foundation For AN/SPY-1 A E.adar Control, Iastsr''’3 
Tiesis, Naval “ postgraduate “ Sciool, Monterey, 
California, pp. 72-73, Derember 1981. 



Parnas, David, L., "Design Software for Ease of 
Extension and Contraction," IEEE Transactions or. 
Software Engine^ina, p. 2 26-2 307~iir cq T979. 



I 




% 







i 

■rf 



I 

S 






Freeman, P.,.and Rassertnaj- A. I 
Dasiqn Techniques, 3rd Edition, 



, Tatorial on Software 
I3EE7"NST7~y5rkr~~frrT77 



Tauseworthe, R.C,, Standardized Development of 
Computer Softw^e, (Faft~ I. !Tetno3s ?af€ lT7 
S’Ean^arSs) Jet "Propulsion LaDocafaofvJ California 
Institute of Technology, Part I: 1975, Part II: 1978, 



Swanson, S,B, , "The Dimensions of ?laintenance, " 
Proceedings 2nd International Conference on Software 
Indineef inq, ~pp , iI92-*r977”T975' . " 



Rome Air Development Center 
Reliabilitx and Maintainabilit 
ii'CoppoIa an3"A7!I. SuitefE,"pp 



Report RADC-TR-79-200, 
7 Management Manual, by 

. TZ7-T5T7”JuIy"Tg7§. 



Cave, W,C., and Salisbury, A, 3. 

Software Life .Cycle - The Project 

TR'PP T*T?5nc!;^r'**“T nn c; o 



IEEE Transactions 
325=3357"Jury"T-57J 



S of tware 



"Controlling the 
Management Task," 
Engine er ing, po. 



Cooper, J.D., "Corporate Level Software Management," 
IEEE Transactions on Software Engineering, po. 
ng-3257"2uIy"T'575. "" 



Daly, E, B. , "Management of Software Development," IEEE 
Tr an sa c-*- ions on Soft wa re Engineering, pp. 22 9- 2 4 2,” 3a y 



MITRE Corporation, DOD Weagons Systems Software 
Acouisition and Management Siu3’y7”3’r R-b?U5, v. ”T7~3uni 
J9757”T13i:?rE~Iccessron"Jor rn"3S§5 2A) . 



Applied Physics Laboratory, Tie John Hookins 
University, Report SR-75-3, DDD '^'eaoon System Software 
Management Studv, by Kossi akof r, "17, "etai. , "June T975 
tD’irC Accession No; AD-A32216D). 



Assistant secretary of Defense, Defense Sysrem 
Software Management Plan, March 1975, (5TIC Accisslon 
IToT"in=I022S55r7 



Stanfield, J.R. , and Skrukrud, A.M., ^^fnware 
Acauisgtion Management Guidebook, Software Mainfenance 
7oIume, S’ysfems “nevelopienfCorp. 7 T3-577Z70Q3’7U2, 

ETovelEer 1977, (DTIC Accession No: AD-A053040) . 



Bersoff, E.H. , Henderson, V.D., and Siegel, S.G., 
"Software Configuration Management: A 'Tutorial," 

Compuzer, pp. 6-l4, January 1979. 



37. 

38. 

39. 

40. 

41 . 

42. 

43. 

44. 

45. 

46. 

47. 

48. 



Naval Postgraduate 3 choa 1 rechnical Report 
NPS-54-82-003, Ivaluation of 3E2NAVINST 3560.1: 
Tactical Diattal Systems" Dotuai3afaE'rcn“'Stariiaf d For 
Soft wa re MalnEe nance, dy ^cneldawr dd, “N'.rr7 Naval 
Fosrgraduate'"dc'RooI7 Monterey, CA, op. 22-24, 1 982. 



Ross, D.T., Goodeneough, J. B., and Irvine, C. A., 
"Software Engineering; Principles, Processes and 
Goals," Computer, p. 55, May 1975. 



Baker, A., "Structured Programaiag in a Production 
Programming Environment," Proceedings of the IEEE 
Inte rna t io nal Conference on da Iiadle "sof tware7~T9757 



Linger, R.C. , and Mills, 3.D., "3n the Development of 
Large Reliable Programs," Sucrent Trends in 
Programming Methodology, Pc entrce-Sall , Englewood 
CrifIs7“New Jef se—dg??. 



Linger, R. C. , Mills, H. D. , and Witt, 3.J., Structured 
Programming: Theory and Practice. Addison-iTesIey 

F'TElisEing Co., “deading'MassacFIusetts, pp. 15-16, 



Wulf, W. A. , "Languages and Strnctured Programs," 
Current Trends in Programming Hethodologv, 
Pf entIce-HaIX7“'Englewood Z life s7“de7~Jsrsev7“Tg777 ■" 



Glass. E.L., and Noiseux. R.A., Software Maintenance 
Giidebook, Prentice-Hall, EngliwoSa “Clift37 “dew 
Jersey, pp. 84- 130, 1931. 



Barnes. J.G.P. , Programming in AOA. Addison-Weslev 
Publishing Co., Reading, lassa cHussicts , 1981. 



Jackson, M.L., Principles of Program Design, Academic 
Press, p. 30, IPTS. 



"Department of Defense Requirements for the 
Programming Environment for the Common High Order 
Language - P SBBL EMAN: R e vise d, " Defense Advanced 

Research Projects Agency, Arlington, Virginia, January 
1979. 



Ritchie- J., and Thompson 3.. "The UNIX Time-Sharino 
System," The Bell System Technical Journal, p. 20,' 
July-August IPTBI ~ ~ 



Marine Corp's Tactical Software Support Activity, 
"Standards and Conventions for Jse of the CMS-2 
Language," Camp Pendeltoi, California, pp. 10-20, 



82 



49. 

50. 

51 . 

52. 

53. 

54. 

55. 

56. 



Liskov, B. H., "A Dasign lethod^Logy for Reliable 
Software Systens,” Prooaedinqs Fall Joinr Sompater 
Conference/ pp. 65-737~T9777" 



Bethke, F.J., et. al., "laproviag tha Usability of 
Programming Publications,” IBM Systems Journal, v. 20, 
No. 3, pp. 306-320, Januatr y~TJ8T. 



Snyders, J. , "User Manuals that Make Sense," Computer 
Decisions, No. 13, pp. 125-123, April 1981. 



Judisctt, J.a. , Rupp, B.A., and Dassinger, R.A., 
"Effects of Manual Style on ?erfornancs in Education 
and Machine Maintenance," IBM Systems Journal, v. 20, 
No. 2, pp. 172- 183, February 1 JaTT "" 



Wilson, L., "Tha Do's and Oon'ts of Documentation," 
» V. 27, pp- 135-185 , September 1981. 



Weinberg, 3.M. , The Psychology of Comoutar 
Programming, Van Nostrand Rein noIT"7o . , p7 5G,”T97T7 



Federal Information Processing Standards Publication 
75 (FIPS PUB-76), Specifications and guidelines for 
Plann ing and U^np a Uana nictlonafy" Svsfem, ”~Unitea 
STanes Department of ~Coimerce7 dationaI“Bur eau of 
Standards, p. 6, 20 August 1930. 



Pressman, Roger S., Software Engineering, A 
Practitioner's Apprcaca, McSfaw^HiIl 5oo5c Company, New 
YorE, op. 72H-230, T'BBZ. 



83 



INITIAL DISTRIB0TI3N LIST 



No. Copies 

1. Defense Technical Information Center 2 

Cameron Station 

Alexandria, Virginia 22314 

2. Library, Code 0142 2 

Naval postgraduate School 

Monterey, California 93940 

3. Department Chairman, Code 54 1 

Department of Administrative Science 

Naval Postgraduate School 
Monterey, California 93940 

4. Department Chairman, Code 52 1 

Department of Comparer Science 

Naval Postaraduate School 
Monterey, California 9394 0 

5. Curricular Officer, Code 37 1 

Computer Systems Technology 

Naval Postgraduate School 
Monterey, California 93940 

6. Professor Norman Lyons, Coie 54Lb 1 

Department of Administrative Sciences 

Naval Postaraduate School 
Monterey, California 93940 

7. Professor Roger Neissinger-3 avion, Sole 54Wr 1 

Department or Aara inistrative Sciences 

Naval Posxgraduate School 
Monrerey, California 93940 

8. LCDS Ronald Modes, Code 52Mf 1 

Department of Computer Science 

Naval Postgraduate School 
Monterey, California 93940 

9. Major W. D. Helling, USMC 1 

2511 Windsor Avenue 

Dubuque, Iowa 52001 

10. LT James Howard Teuscher, J3N 2 

Post Office Box 46 

Wells, New York 1 2190 



84 



» r 





200174 




Thesis 

T358 

c.l 



Thesis 

T358 Teuscher 
c.l Software engineer- 

ing practices: 
their impact on the 
design of a program 
maintenance manual. 

13 APR r. »* o q I’ 0 O 

V { |i o 

NOV 20 65 m 3 7 






Teuscher 

Software engineer- 
ing practices; 

their impact on the 
design of a program 
maintenance manual. 



